agent-dir 0.4.1 → 1.0.0

package/docs/MCP.md

@@ -0,0 +1,106 @@
+# MCP interface and security model
+
+Agent Dir exposes a local project through an authenticated, stateless Model Context Protocol endpoint.
+
+## Endpoint and authentication
+
+- `POST /mcp` is the application MCP endpoint and requires authentication.
+- `HEAD /__health` is reserved for local tunnel health checks and does not expose project contents.
+- Legacy direct filesystem REST routes such as `/__tree` and direct `GET`/`PUT`/`DELETE` file paths are not supported.
+
+Use the Bearer token in the standard header:
+
+```http
+Authorization: Bearer <token>
+```
+
+The server also accepts a query-string token for clients that cannot set an Authorization header. Prefer the header because query-string tokens can be exposed in URLs and logs.
+
+## Stateless protocol behavior
+
+The implementation supports MCP protocol version `2026-07-28`. Requests carry protocol version and client capabilities in `params._meta`; this path does not require an initialize handshake or `Mcp-Session-Id`.
+
+Standard Streamable HTTP requests do not need implementation-specific `MCP-Protocol-Version`, `Mcp-Method`, or `Mcp-Name` headers. If supplied, these headers are validated against the JSON-RPC request and metadata.
+
+Supported features include:
+
+- `server/discover`
+- cursor pagination for list-style methods
+- `subscriptions/listen` for tool, prompt, and resource change events
+- resource subscriptions and filesystem change notifications
+- cache metadata
+- structured tool results with `resultType` and `outputSchema`
+- the stable `io.modelcontextprotocol/skills` extension
+
+Modern `subscriptions/listen` replaces the legacy GET/SSE notification model. List-style methods use opaque cursors when more than 50 entries are available.
+
+## Public tool set
+
+The core public tool set is intentionally small:
+
+| Tool | Purpose |
+| --- | --- |
+| `project_context` | Compact project overview and active execution policy |
+| `find_files` | Find paths by glob |
+| `search_code` | Search source-like files with bounded output |
+| `find_symbol` | Locate likely symbol definitions |
+| `find_references` | Locate symbol references |
+| `read_range` | Read a bounded line range from a UTF-8 file |
+| `apply_changes` | Create, patch, or delete files |
+| `file_info` | Inspect filesystem metadata |
+| `validate` | Run lightweight diagnostics and explicitly requested allowed npm scripts |
+| `run_npm_batch` | Run explicitly allowlisted npm scripts sequentially |
+| `run_command_batch` | Run explicitly allowlisted executables sequentially without a shell |
+| `codegraph_explore` | Optional structural code intelligence when CodeGraph is available |
+
+`codegraph_explore` is only advertised when CodeGraph is installed and the current project has a readable `.codegraph/codegraph.db` index. Other CodeGraph tools are not forwarded.
+
+Batch command operations execute sequentially and stop at the first failed command. Tool results include structured content and a serialized text representation; tools returning structured data advertise an output schema.
+
+## Command execution policy
+
+npm scripts and other executables use separate allowlists. An executable not in the configured allowlist is rejected, and configured `blacklistedCommands` prefixes override the allowlist. Commands are launched without a shell.
+
+Git is run through `run_command_batch` when `git` is allowlisted. There are no dedicated Git MCP tools. This keeps the advertised tool set small while preserving explicit executable and argument restrictions. Avoid allowing shells or interpreters unless broader command execution is intentional.
+
+## CodeGraph integration
+
+CodeGraph is optional and installed separately:
+
+```bash
+npm install -g @colbymchenry/codegraph
+codegraph init
+```
+
+Agent Dir exposes `codegraph_explore` only when the executable is on `PATH` and the current project has a readable index. It starts CodeGraph on first use and reuses the child process for subsequent calls. The project root is fixed as the CodeGraph path; callers cannot forward arbitrary `projectPath` values. Agent Dir passes a limited environment to the child process and terminates it during shutdown.
+
+Discovery distinguishes these states:
+
+- `not_installed` — CodeGraph is unavailable on `PATH`.
+- `not_indexed` — installed, but this project has no readable index.
+- `available` — installed and indexed.
+- `startup_failed` / `runtime_failed` — CodeGraph failed to start or later terminated; Agent Dir remains available.
+
+When indexed, agents are instructed to use CodeGraph for non-trivial structural questions such as call/data flow, symbol relationships, and change impact. Exact-text searches and focused file edits use Agent Dir's native tools.
+
+## Agent instructions and Skills
+
+`server/discover` returns dynamically generated instructions. The Resources primitive exposes:
+
+```text
+agent-dir://instructions
+agent-dir://capabilities
+```
+
+The capabilities resource reports the Agent Dir version, registered tool names, execution policy, and preferred/avoid tool-selection patterns.
+
+Agent Dir implements the stable MCP Skills extension (`io.modelcontextprotocol/skills`) and discovers project-local `SKILL.md` files under:
+
+```text
+skills/
+.agents/skills/
+.claude/skills/
+.github/skills/
+```
+
+Skills are exposed through `skills/list`, `skills/get`, `resources/list`, and `resources/read`. Skill manifests are bounded to 512 resources and 16 MiB. Binary supporting files are returned as MCP blobs; `resources/directory/read` lists direct children of a skill resource directory.

package/docs/RELEASING.md

@@ -0,0 +1,213 @@
+# Releasing agent-dir
+
+This document is the authoritative maintainer/agent procedure for publishing `agent-dir`.
+
+## Architecture
+
+    feature/*
+        │
+        ├── PR → staging
+        │        └── CI
+        │
+        └── promotion PR → main
+                 └── CI
+                      │
+                      ▼
+            .github/workflows/publish.yml
+                      │
+                      ├── npm run check
+                      ├── npm test
+                      ├── npm pack --dry-run
+                      └── npm run release
+                             │
+                             └── semantic-release
+                                  ├── determine SemVer
+                                  ├── update package.json/package-lock.json
+                                  ├── commit release
+                                  ├── create vX.Y.Z tag
+                                  ├── create GitHub Release
+                                  └── publish npm package
+
+`main` and `staging` are protected. Normal human and agent changes reach them through pull requests.
+
+## Release source of truth
+
+- `.releaserc.json` — semantic-release configuration
+- `.github/workflows/publish.yml` — production release workflow
+- `package.json` — package metadata and release script
+- npm Trusted Publishing/OIDC — npm authentication for GitHub Actions
+
+The workflow filename `publish.yml` is intentional. Do not rename it. npm Trusted Publishing is configured against the workflow identity.
+
+The semantic-release repository URL uses SSH: `git@github.com:SarfDime/agent-dir.git`.
+
+The release workflow uses the repository's release SSH key to allow semantic-release to update protected `main` with its release commit/tag.
+
+## Normal release procedure
+
+### 1. Make the change
+
+Work on a feature branch. Keep the change focused. Use a Conventional Commit message whose type reflects the intended release impact.
+
+Examples: `fix: handle tunnel reconnect`, `feat: add project snapshots`, `feat!: change authentication protocol`.
+
+Do not manually edit the package version.
+
+### 2. Validate locally
+
+    npm run check
+    npm test
+    npm pack --dry-run
+
+`npm pack --dry-run` is important: inspect the file list and make sure the package does not contain credentials, local configuration, development-only files, or other unintended content.
+
+### 3. Merge through staging
+
+Push the feature branch and open a PR targeting `staging`.
+
+The required CI check is `Check`. It runs `npm ci`, `npm run check`, `npm test`, and `npm pack --dry-run`.
+
+Do not bypass a failing check. After checks pass, merge the PR into `staging`.
+
+### 4. Promote staging to main
+
+Create a promotion PR: `staging → main`.
+
+CI runs again because `main` is also a pull-request target. Merge only after the required `Check` status is green.
+
+### 5. Let GitHub Actions publish
+
+The merge to `main` creates a push to `main`, which starts `.github/workflows/publish.yml`.
+
+The workflow validates the package again and invokes `npm run release`.
+
+Do not run `npm publish` locally and do not manually create a release tag.
+
+semantic-release reads the Conventional Commit history since the previous release and decides whether a release is required.
+
+## Version rules
+
+| Change | Version impact |
+|---|---|
+| `fix:` | patch |
+| `feat:` | minor |
+| `feat!:` | major |
+| `BREAKING CHANGE:` footer | major |
+| `docs:` | none |
+| `test:` | none |
+| `chore:` | none |
+| `refactor:` | none |
+| `ci:` | none |
+
+There is an explicit semantic-release rule: `fix(ci)` has `release: false`.
+
+A CI-only repair can be promoted to `main` without creating a package release. Do not change its commit type merely to force publication.
+
+## What semantic-release changes
+
+When a release is required, semantic-release is responsible for:
+
+- calculating the next SemVer version;
+- updating `package.json`;
+- updating `package-lock.json`;
+- creating the release commit with `[skip ci]`;
+- creating the `vX.Y.Z` Git tag;
+- creating the GitHub Release;
+- publishing the package to npm.
+
+The release commit is `chore(release): <version> [skip ci]`. The release commit itself must not start another release cycle.
+
+## npm authentication
+
+npm publishing is performed by GitHub Actions using npm Trusted Publishing/OIDC.
+
+The workflow requests `id-token: write`. Do not add an npm token to the workflow unless the publishing architecture is deliberately changed and reconfigured.
+
+Do not expose or print npm credentials.
+
+`GITHUB_TOKEN` is separate from npm authentication and is used by semantic-release for GitHub release operations. The repository currently supplies the release workflow's GitHub credential through the `RELEASE_TOKEN` Actions secret.
+
+## Protected-branch automation
+
+The release workflow needs to write the semantic-release commit/tag back to `main`, even though normal pushes to `main` are blocked.
+
+That automation is authorized separately through the release SSH deploy key stored in the `RELEASE_DEPLOY_KEY_B64` Actions secret.
+
+Do not remove or replace this mechanism casually. If it must change, verify the complete release flow and npm Trusted Publishing configuration before merging the change.
+
+The intended security boundary is:
+
+- humans/agents: PR-only changes;
+- release automation: narrowly authorized to perform the semantic-release update on `main`.
+
+## How to verify a release
+
+After a release-worthy change reaches `main`, verify:
+
+1. The `Release` workflow completed successfully.
+2. semantic-release reported the expected next version.
+3. The repository has a matching `vX.Y.Z` tag.
+4. The GitHub Release exists for that tag.
+5. npm reports the expected package version.
+6. `package.json` and `package-lock.json` on `main` contain the released version after the release commit.
+
+The package version and release tag must agree: `package.json version = X.Y.Z` and `Git tag = vX.Y.Z`.
+
+## When a release does not happen
+
+A successful `Release` workflow can legitimately produce no release when commits since the previous release contain no release-worthy Conventional Commit.
+
+Examples: `docs: update README`, `test: add regression coverage`, `chore: update development tooling`, `fix(ci): correct workflow configuration`.
+
+Do not interpret a successful workflow with no release as a publishing failure.
+
+## Release failure recovery
+
+When a release fails:
+
+1. Inspect the exact failing workflow step.
+2. Determine whether semantic-release calculated a release.
+3. Check the latest Git tag.
+4. Check the current npm published version.
+5. Check whether a GitHub Release was created.
+6. Check whether the release commit was created.
+7. Only then decide whether another change or rerun is appropriate.
+
+Do not manually bump the version, move/delete/recreate an existing release tag, run `npm publish` from a workstation, create a second tag for the same version, or rewrite commit history just to make semantic-release produce a version.
+
+If a release was partially created, reconcile the actual Git/npm/GitHub state before making another release attempt.
+
+## CI workflow constraints
+
+`.github/workflows/ci.yml` runs for pull requests targeting `staging` and `main`.
+
+Its concurrency key must remain safe for both PR events and any diagnostic/manual event that may temporarily be introduced:
+
+    group: ci-${{ github.event.pull_request.number || github.ref }}
+
+Do not replace this with a direct `pull_request.number` reference.
+
+The production release workflow intentionally runs only on pushes to `main`:
+
+    on:
+      push:
+        branches:
+          - main
+
+Keep release execution serialized:
+
+    concurrency:
+      group: release
+      cancel-in-progress: false
+
+## Files an agent should inspect first
+
+    AGENTS.md
+    docs/RELEASING.md
+    .releaserc.json
+    package.json
+    .github/workflows/ci.yml
+    .github/workflows/publish.yml
+    .github/CONTRIBUTING.md
+
+Do not assume the release process from generic npm conventions. This repository's protected-branch and Trusted Publishing configuration is intentional.

package/docs/telemetry.md

@@ -0,0 +1,109 @@
+# Telemetry interpretation
+
+Agent Dir telemetry is a local operational record of MCP activity. It describes what the server handled, how long it took, and where failures occurred without recording project contents, command arguments, tokens, environment variables, or project paths at standard levels. The opt-in diagnostic level additionally records local troubleshooting metadata, including project paths, hostname, username, process identifiers, full Node version, Linux distribution ID/name/version, kernel version, memory usage, process uptime, and bounded raw tool inputs/outputs or error details. Diagnostic records can contain source code, command arguments, project data, and other sensitive material; they are stored locally and should be enabled only when intended.
+
+## Data hierarchy
+
+Telemetry is organized as:
+
+- `none`: disabled.
+- `anonymous`: operational events without runtime/project context.
+- `basic`: anonymous events plus coarse runtime context.
+- `detailed`: basic context plus coarse project classification.
+- `diagnostic`: detailed context plus identifying/troubleshooting metadata and bounded raw tool input/output or error details. This can contain source code, command arguments, and sensitive project information; it is stored locally. Use only when intended.
+
+configuration → session → event
+
+- **Configuration** identifies the Agent Dir configuration that produced the event. Named profiles use the profile name; direct CLI configurations use a stable hash of the effective share configuration.
+- **Session** identifies one MCP handler lifetime. A session starts with its first MCP request and is finalized when the server closes the handler.
+- **Event** is one recorded operation or one session-finalization record.
+
+## Event types
+
+### mcp_request
+
+One MCP/JSON-RPC request handled by Agent Dir. Its duration covers the request from entry through response/error handling.
+
+### tool_call
+
+One Agent Dir tool execution inside an MCP request. Tool metrics are the best measure of individual Agent Dir capability reliability. Tool events include UTF-8 input/output byte counts, a rough token-size estimate (`ceil(bytes / 4)`), hashed request/input/output fingerprints, output repetition within the current process session, and bounded per-file metadata. File metadata contains hashes of paths and returned file text plus byte counts; it does not contain the paths or text themselves. A matching output fingerprint means the serialized tool result was identical, not that Claude necessarily re-read or billed those bytes again.
+
+Token estimates are **not tokenizer measurements** and do not represent Claude's actual input/output tokens or billing. Agent Dir cannot observe Claude's hidden prompt, cached tokens, reasoning tokens, or context carried between turns. Search results can be compared by result count, output bytes, truncation, and pagination, but Agent Dir does not currently judge semantic search relevance. Repeated input fingerprints and event ordering can help identify retry patterns, while validation-after-change counts must be inferred from the raw event sequence rather than treated as a definitive causal metric.
+
+### command_call
+
+One command operation performed by an Agent Dir command tool. Command metrics describe command execution separately from MCP transport success.
+
+### session
+
+A final summary emitted when the MCP handler closes. It contains:
+
+- wallClockDurationMs: elapsed time from the first request to the last request.
+- activeRequestDurationMs: sum of MCP request processing durations.
+- idleGapDurationMs: wall-clock time minus active request time.
+- requestCount: number of MCP requests in the session.
+- toolCallCount: number of tool calls in the session.
+- commandCallCount: number of command operations in the session.
+
+Idle gaps are **not agent thinking time**. They can contain agent reasoning, network latency, client delays, scheduling, or other time outside Agent Dir request processing.
+
+## Success rates
+
+There is intentionally **no single overall success rate**.
+
+An MCP tool invocation normally produces both a tool_call event and an enclosing mcp_request event. Counting both as independent successes or failures would double-count the same operation and make the metric misleading.
+
+Instead, interpret these independently:
+
+- **MCP success** = successful MCP requests / MCP requests.
+- **Tool success** = successful tool calls / tool calls.
+- **Command success** = successful command calls / command calls.
+- **Per-tool success** = successful calls for that tool / calls for that tool.
+- **Per-command success** = successful calls for that command operation / calls for that command operation.
+
+A rate of — means there were no events of that type, not that the type failed.
+
+## Failures
+
+Failure categories are separated by event type:
+
+- mcp failures belong to MCP request handling.
+- tool failures belong to Agent Dir tool execution.
+- command failures belong to command execution.
+
+This separation prevents a failed tool call and its failed enclosing MCP request from being presented as one combined failure metric.
+
+## Duration metrics
+
+- **Avg** is the arithmetic mean of recorded durations for that operation.
+- **P95** is the 95th-percentile recorded duration using the nearest observed sample at or above the percentile rank.
+- Session wall-clock time is not equivalent to active server processing time.
+
+Do not infer agent reasoning time, user wait time, or network latency from tool duration alone.
+
+## Privacy levels
+
+- **anonymous** records operational event data only.
+- **basic** adds bounded Agent Dir/runtime and MCP client information.
+- **detailed** additionally adds coarse project classification such as language, package manager, Git/CodeGraph availability, and project size.
+- **diagnostic** additionally adds local troubleshooting metadata such as project paths, hostname, username, process identifiers, Node version, memory usage, and process uptime. This level is opt-in and should only be enabled when needed for local diagnosis.
+
+Telemetry is persisted locally only when enabled. Persistence failures must never affect MCP request handling.
+
+## Reading telemetry show
+
+telemetry show is the raw event stream grouped by configuration and session. Use it when exact event order, timestamps, event fields, or individual failures matter.
+
+## Reading telemetry summary
+
+telemetry summary is an aggregation for humans and agents. Prefer its separate MCP/tool/command success rates and per-tool/per-command metrics for reliability analysis. Use the raw stream when investigating a specific request or reconstructing event order. Raw tool events currently provide the token-size, fingerprint, duplicate-output, and file-metadata signals described above; aggregated summary fields for those measurements have not yet been added.
+
+## Data quality rules
+
+Telemetry should be treated as measurement data, not as a complete audit log:
+
+1. Session records are only emitted when a handler closes normally through Agent Dir shutdown.
+2. An active session may therefore have no session event yet.
+3. Legacy persisted session records without the current timing fields are identified separately and are not used as current session timing data.
+4. Event counts include session records, because they are recorded telemetry events; success rates exclude session records because sessions are summaries, not operations.
+5. MCP request and tool events are deliberately not combined into one reliability denominator.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dir",
-  "version": "0.4.1",
+  "version": "1.0.0",
   "description": "Expose a local project to an AI agent through authenticated MCP, filesystem tools, and allowlisted development commands",
   "repository": {
     "type": "git",
@@ -14,6 +14,9 @@
     "dist/bin",
     "dist/src",
     "README.md",
+    "docs",
+    "assets/agent-dir-banner.svg",
+    "SECURITY.md",
     "LICENSE"
   ],
   "engines": {