cortexfs-extension-development

# CortexFS Extension Development Build executable Tool SDK and Agent SDK extensions without adding a root ABI, provider special case, watcher, queue, or alternate orchestration path. ## Workflow 1. Read `docs/architecture.md`, `docs/naming-guide.md`, and the relevant files under `docs/spec/` before changing an ABI surface. 2. Use CodeGraph before text search when `.codegraph/` exists. 3. Reuse the Rust SDK matching the object class: `cortexfs-tool-sdk` for tools and `cortexfs-agent-sdk` for agents. 4. Implement one executable per object. Tools accept argv or stdin; agents accept only the hosted typed invocation envelope. Emit canonical JSONL. The Agent SDK entrypoint performs the runtime startup capability ping; do not bypass it. Keep model-provider formats outside the extension contract. Treat `CTX_SOURCE` only as a candidate path: runtime receipt dev/inode/type is authoritative for durable writes. Every Agent SDK extension must set the required agent control `abi` to `sdk-envelope-v1`. Follow the normative [Agent Runtime envelope](../../../docs/spec/agent-runtime.md) rather than duplicating its schema in extension documentation. 5. Create a strict `cortexfs.object/v2` manifest with an object SemVer and a Cargo-style CortexFS SemVer requirement. Use `cortexfs.object/v1` only for an intentionally legacy manifest, and then omit `version` and `compatibility` completely. Read `references/manifest.md` before choosing controls, compatibility, or an install tier. 6. Build the executable, calculate its SHA-256, and place the exact digest in the object manifest. For a distributed `cortexfs.package/v1` bundle, also place the exact lowercase digest in every tool and agent `sha256` field. Do not put commands, arguments, wrappers, secrets, or policy grants for unrelated objects in the manifest. 7. Validate source and manifest changes without installing first. Run `ctx object check MANIFEST` for each rendered manifest; it requires no source tree and performs no backing-tree writes. A v2 manifest incompatible with the compiled CortexFS version is invalid and exits 2. For a local source `cortexfs.package/v1` bundle, run `ctx install --check PACKAGE`. For a distributed/prebuilt bundle, run `ctx install --check --require-hashes PACKAGE`; declared digests are always checked and this flag also rejects missing digests. Both modes render and check every object without writing a backing tree. Follow `references/testing.md` for the staged test ladder. 8. Perform installation only after an explicit mutation request. Invoke `ctx object install --source PATH MANIFEST --tier user|system`, where PATH is the durable backing tree. Never use `/ctx`, `CTX_ROOT`, or `--root` as the writable target, and never copy directly into a live object directory. 9. For an existing receipt-managed object, validate a v2 candidate and dry-run `ctx object replace|upgrade|rollback --source PATH MANIFEST --tier user|system`. Apply only after an explicit mutation request by adding `--yes`. Use `replace` for v1 migration or unordered replacement, `upgrade` only for a higher v2 version, and `rollback` only for a lower caller-supplied v2 manifest and artifact. 10. Verify discovery, metadata, policy denial, authorized execution, JSONL ordering, and durable agent behavior through the installed path. ## Boundaries - Keep `/ctx/status`, `/ctx/bin`, `/ctx/model`, `/ctx/agent`, `/ctx/tool`, `/ctx/home`, and `/ctx/shared` as the only root classes. - Treat installation as new-object-only and replacement as a separate explicit lifecycle. Candidates are always v2. Replacement may migrate a receipt-managed v1 or v2 object; upgrade and rollback require current v2 and strict higher/lower ordering. CortexFS stores no version history, so rollback requires the caller's old manifest and artifact. - Treat the executable publication as the object commit boundary. Do not fabricate runtime-owned `status`, `pid`, `log`, or socket state. - Keep tool installation separate from authorization. Installing a tool must not edit an agent policy. - Treat v2 compatibility as install-admission metadata, not authority. It does not grant policy access or start a runtime, and a later mismatch must not prevent receipt-managed uninstall. - Treat replacement as dry-run unless `--yes` is explicit. It uses a same-filesystem stage, hides the old executable first, and publishes the new executable last. It is not pair-atomic and may retain safety residue on a conflict; it must not intentionally replace a foreign inode at receipt checkpoints. - Quiesce the matching runtime and same-authority writers before applied replacement. The lifecycle command does not stop/start a runtime, grant policy, create sockets, or retain a version archive. - Install user tools under `/ctx/home/<effective-uid>/tool` and system tools under `/ctx/tool`. Install agents under `/ctx/agent`; although the root ABI defines `/ctx/home/<effective-uid>/agent`, neither manifest schema carries tier identity to the root socket runtime, so the installer rejects user-tier agents. - Use Git commits or process restarts as development refresh boundaries. Do not add polling, watchers, or hot reload. - Preserve executable plugins as the supported extension path. Do not claim the Tool SDK `DynamicTool` loader or native resident cache is wired into the core runtime until a core consumer and end-to-end proof exist. - Treat package hashes as descriptor-to-payload integrity, not publisher or registry authentication. `cortexfs.package/v1` has no signature field; use an authenticated trusted channel to acquire its descriptor and digests. ## Canonical Example Use `examples/extensions/echo/` as the canonical paired extension. It contains one Tool SDK executable, one Agent SDK executable, strict manifest templates, and an explicitly opted-in installer that installs the tool before the agent. Link to this example instead of copying it into skill resources. ## References - `references/manifest.md` — manifest schema, controls, tiers, and security. - `references/testing.md` — read-only validation and opt-in live acceptance.