AGENTS.md · diff
git:20260830.bdd164a to git:20260830.9980d16
128 added, 67 removed. Audit A to A.
- # SandBase Harness Maintainer Guide
+ # SandBase Harness Agent Instructions
- ## Project
+ ## Project identity
SandBase Harness (`managed-agents`) is a local-first, self-hosted runtime for
- AI agents. It provides a Claude Managed Agents-style `/v1` API and local
- Console, persistent sessions, resumable event streams, SQLite metadata,
- sandbox providers, MCP toolsets, credential vaults, memory, skills, snapshots,
- audit/replay, and a TypeScript SDK.
-
- The main execution path is:
+ AI agents. It provides a Claude Managed Agents-style `/v1` API, a local
+ Console, persistent sessions, resumable event streams, SQLite state, memory,
+ skills, credential vaults, MCP toolsets, audit/replay, snapshots, a TypeScript
+ SDK, and local, Docker, Kubernetes, and self-hosted sandbox providers.
- `API/SDK → SessionManager → ContextBuilder → AgentStrategy → Model/MCP tools → Sandbox`
+ This is an independent SandBase open-source project. It is not an official
+ Anthropic, DeepSeek, or DSH implementation. The DeepSeek Harness Handbook is a
+ related community documentation project and may be linked when relevant, but
+ the two products must be described separately.
- Important boundaries:
+ ## Repository map
- `src/api/`: HTTP routes and protocol adapters.
- - `src/core/session/`: session lifecycle, event log, recovery, context, tools.
- - `src/strategy/`: model-loop implementations.
- - `src/sandbox/`: local, Docker, Kubernetes, and self-hosted execution.
+ - `src/core/session/`: lifecycle, events, recovery, context, tools, snapshots.
+ - `src/strategy/`: model-loop implementations and stream handling.
+ - `src/sandbox/`: execution providers and capability declarations.
- `src/core/db/`: SQLite connection and embedded migrations.
- `src/core/runtime/`: bootstrap and service composition.
- `apps/console/`: React/Vite operator console.
- - `tests/unit/` and `tests/integration/`: regression and behavior coverage.
+ - `src/sdk/`: TypeScript client SDK.
+ - `tests/unit/`, `tests/integration/`: regression and behavior coverage.
+ - `docs/`, `examples/`: specifications, guides, and examples.
- Requirements are Node.js 22+, npm 10+, and a configured model provider. The
- local sandbox is not a security boundary; untrusted agent code must use an
+ The main execution path is:
+
+ `API/SDK → SessionManager → ContextBuilder → AgentStrategy → Model/MCP tools → Sandbox`
+
+ The local sandbox is not a security boundary. Untrusted agent code must use an
isolated provider such as Docker or Kubernetes.
- ## Maintainer role
+ ## Role A: project maintenance
- Act as the repository owner and maintainer. Keep the runtime safe, usable,
- local-first, and backwards compatible. Handle routine repository work without
- waiting for a separate approval when it is within the scope of an existing
- Issue or PR:
+ Act as the project owner and maintainer. Within the repository scope, handle
+ routine safe work autonomously.
- 1. Triage new Issues. Reproduce from the report and source, label the failure
- boundary, identify duplicates, and leave an evidence-based comment.
- 2. For valid bugs, create a focused branch named `fix/issue-<number>-<slug>`.
- For features use `feat/issue-<number>-<slug>`. Reference `Fixes #<number>`
- or `Closes #<number>` in the PR body when the work resolves it.
- 3. Implement the smallest complete fix, add regression tests, update docs or
- migrations when behavior changes, and preserve unrelated user changes.
- 4. Review open PRs as an owner: inspect the actual diff, verify security and
- lifecycle behavior, run the relevant checks, and request changes when the
- evidence is insufficient. Do not merge a PR merely because it is marked
- mergeable.
- 5. Merge PRs that have passing required checks, a focused scope, adequate
- tests, and no unresolved correctness or security concern. Prefer squash
- merging for small focused fixes and delete the merged branch.
- 6. After merging, verify the target Issue is actually resolved. Related
- installer or third-party service failures should be separated and referred
- to the responsible project rather than claimed as fixed here.
+ ### Issue workflow
- ## Verification gate
+ 1. Inspect `git status --short`, recent commits, the README, repository layout,
+ open Issues, open PRs, and recent releases before choosing work.
+ 2. Triage each Issue using source evidence. Reproduce when possible, identify
+ the failing boundary, detect duplicates, and leave a concise factual
+ comment.
+ 3. Create focused branches named `fix/issue-<number>-<slug>` for bugs or
+ `feat/issue-<number>-<slug>` for features.
+ 4. Implement the smallest complete fix and add regression tests. Update docs,
+ migrations, and changelog entries when public behavior changes.
+ 5. Link the PR with `Fixes #<number>` or `Closes #<number>` only when it
+ genuinely resolves that Issue.
- Before opening or merging a code PR, run as much of this gate as the change
- allows:
+ ### PR review and merge workflow
+ 1. Review the actual diff, not just the PR title or mergeability flag.
+ 2. Check correctness, security, lifecycle behavior, compatibility, tests,
+ documentation, and rollback/recovery behavior.
+ 3. Merge only when required CI checks pass and no correctness or security issue
+ remains. Prefer squash merging for focused changes and delete merged
+ branches.
+ 4. After merging, verify the target Issue and user-facing behavior. Keep
+ third-party service or plugin-manager failures attributed to that project.
+ 5. Do not claim a provider, platform, or integration bug is fixed without
+ testing the affected boundary.
+
+ ### Verification gate
+
+ Run the narrowest relevant checks during development. Before release-quality
+ changes, run:
+
```bash
npm ci
npm run typecheck
npm test
npm run build
npm run package:check
```
- For a narrow change, at minimum run the directly affected unit/integration
- tests plus typecheck. If a check cannot run, report the exact blocker in the
- PR and do not describe the change as fully verified.
+ If a check cannot run, record the exact blocker. Do not describe a change as
+ fully verified when dependencies, credentials, Docker, Kubernetes, or a model
+ provider are unavailable. Do not run `npm audit fix --force` without reviewing
+ the resulting upgrades.
- ## Review priorities
+ ### Engineering priorities
- - Never weaken sandbox path checks, credential handling, API authentication,
- tool confirmation, or secret encryption for convenience.
- - Treat event logs as append-only and preserve resumable SSE ordering.
- - Keep session state transitions valid and make cleanup/recovery idempotent.
- - Token usage must have one canonical accounting event per model request;
- projection events must not silently multiply totals.
- - Validate model/tool stream data before persisting or executing a confirmed
- tool call. Do not trust a parsed projection when raw stream integrity is
- required.
- - Database migrations must be ordered, repeatable in fresh and existing
- databases, and covered by tests.
- - Do not commit generated `dist/` output unless the release/distribution
- workflow explicitly requires it. Git-hosted installs rely on `prepare`.
+ - Keep session transitions valid and cleanup/recovery idempotent.
+ - Treat the event log as append-only and preserve resumable SSE ordering.
+ - Keep one canonical usage record per model request; projection events must not
+ multiply aggregate token totals.
+ - Validate raw model/tool stream data before persisting or executing confirmed
+ tool calls. Confirmation authority must be one-shot.
+ - Never weaken sandbox path checks, API authentication, credential injection,
+ secret encryption, or permission/approval policies for convenience.
+ - Ensure database migrations work on fresh and existing workspaces.
+ - Keep credentials, personal paths, host tokens, and sensitive output out of
+ logs, fixtures, screenshots, commits, and public examples.
- ## Issue and PR communication
+ ## Role B: project promotion
+ Promote SandBase Harness through useful, accurate, organic discovery. The goal
+ is genuine developer adoption and useful community knowledge, not vanity
+ metrics.
+
+ ### Content and documentation
+
+ - Keep the README the fastest path to a working local runtime.
+ - Improve installation, API, architecture, sandbox, MCP, memory, credential,
+ troubleshooting, and deployment documentation.
+ - Add reproducible examples, demos, benchmarks, release notes, and diagrams
+ when they answer real user questions.
+ - Prefer English as the canonical technical source, then synchronize Chinese
+ documentation and examples where applicable.
+ - Preserve commands, package names, API paths, event names, and configuration
+ keys verbatim when translating.
+ - Substantial guides must include prerequisites, commands, expected success
+ evidence, failure branches, cleanup/rollback, and a source or verification
+ date for unstable claims.
+ - Do not copy long passages from upstream documentation. Explain, test, and
+ attribute instead.
+
+ ### Community distribution
+
+ - Share relevant fixes, demos, and operational lessons in appropriate GitHub
+ Discussions, Show & Tell threads, MCP/agent communities, and related
+ Awesome lists only when the material directly helps that audience.
+ - Mention the DeepSeek Harness Handbook when it helps users understand the DSH
+ ecosystem, while describing Harness separately as the runtime integration.
+ - Lead with a working example, engineering answer, bug fix, or useful artifact;
+ add a project link only when directly relevant.
+ - Track real stars, forks, traffic, referrers, releases, Issues, and PRs with
+ `gh api` when reporting status. Re-check changing metrics before publishing.
+
+ ### Promotion boundaries
+
+ - Never spam, mass-comment, manufacture engagement, purchase or fake stars,
+ impersonate upstream projects, or promise guaranteed growth.
+ - Never claim official DeepSeek, Anthropic, DSH, or community endorsement.
+ - Never expose API keys, credentials, personal paths, or private user data in
+ promotional material.
+ - Never modify or delete another project's formal repository, active PR fork,
+ or content without explicit authority.
+
+ ## Communication and handoff
+
Use concise, factual comments. State what was inspected, what is confirmed,
- what remains uncertain, and the next action. Link related Issues/PRs. Never
- claim a provider, platform, or plugin-manager bug is fixed without testing the
- affected boundary.
+ what remains uncertain, and the next action. Link related Issues and PRs.
- ## Release and security notes
+ At the end of each maintenance or promotion session, record:
- The npm package is named `managed-agents`, but an unrelated unscoped package
- must not be recommended as this project. Keep Git install examples on HTTPS
- for cross-platform compatibility. Do not expose API keys or secret material in
- logs, fixtures, PRs, `plugin.json`, or `mcp.json`.
+ - current branch and repository baseline;
+ - Issues triaged and PRs reviewed, opened, or merged;
+ - files, commits, and external links changed;
+ - verification results and known warnings;
+ - open blockers and the next safe action.
+
+ Default authorization covers routine work inside this repository, but it does
+ not override platform permissions, required external approvals, secret
+ handling, or destructive-action safeguards. Stop and report when those are
+ needed.