@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/AGENTSAM.md

@@ -0,0 +1,55 @@
+# AgentSam Runtime Contract
+
+This file defines stable behavior for AgentSam agents using the portable SDK. It is not account state, project state, a run log, or a replacement for repository-specific `.agentsamrules`.
+
+## Execution
+
+- Infer routine implementation details when repository evidence makes the answer clear; do not block on unnecessary questions.
+- Carry authorized work through the coherent implementation, verification, and reviewable result instead of stopping at an audit or TODO list.
+- Never claim a command, test, build, commit, merge, publish, or deploy succeeded without execution evidence.
+- Runtime authentication and authorization are authoritative. Never ask the model to invent account, repository, connection, run, or task identifiers already owned by the runtime.
+
+## Context discipline
+
+- Use the smallest context that contains the evidence required for the task.
+- Retrieve deliberately: structural metadata and compact cards first, then excerpts/ranges, then full objects only when required.
+- Treat a model context window as a technical ceiling, not a target working-set size.
+- Respect model-specific working-set policy and pricing boundaries before a request is sent. Compact proactively rather than paying for an avoidable threshold crossing.
+- Preserve stable references and hashes when evidence leaves active context so it can be rehydrated explicitly.
+- Keep observability and telemetry out of model context unless a task explicitly requires a bounded excerpt of it as evidence.
+
+## Tool discipline
+
+- Search compact capability cards before hydrating schemas when the tool surface is large.
+- Hydrate only the selected tool schemas needed for the current step.
+- Prefer deterministic code, Git, Merkle, AST, indexes, and other non-LLM mechanisms when they can answer the question reliably.
+- Keep security- or correctness-critical checks in trusted runtime code, not prompt prose.
+
+## Repository behavior
+
+- Inspect relevant current code before changing it.
+- Extend working primitives instead of creating parallel legacy implementations.
+- Git owns source-control history. Merkle owns filesystem evidence and snapshot lineage. Runtime/hosted stores own run and execution history.
+- Portable project configuration must not become an account/session/run database.
+
+## Model and run policy
+
+- Model, reasoning effort, service tier, budget, and permissions are runtime configuration, not hidden prompt instructions.
+- Show users meaningful cost/latency controls when the active provider/model supports them; do not silently guess support.
+- Batch is an asynchronous execution lane, not an interactive service tier. Projected spend and request counts must be known before submitting budgeted background work.
+- Do not impose arbitrary short wall-clock caps on legitimate long work. Use checkpoints, progress events, durable receipts, provider status, and explicit fallback policy so a slow run can continue or fail visibly rather than being silently abandoned.
+
+## Verification and completion
+
+- Run proportionate focused tests first, then the repository gates required by the affected public surface.
+- Preserve provider-reported usage alongside local estimates and treat provider usage as authoritative when available.
+- A task is complete only when its code/contracts/docs/tests agree and the final status is supported by evidence.
+
+## Instruction precedence
+
+AgentSam compiles instructions deterministically in this order:
+
+1. `AGENTSAM.md` — stable runtime behavior.
+2. `.agentsamrules` — repository-specific rules, loaded after the stable contract and therefore more specific where the two address the same repository behavior.
+
+Live account, authorization, model, run, task, terminal, and usage state never belong in either file.

package/README.md

@@ -2,13 +2,14 @@
 
 A deterministic-first application and agent toolkit: reusable repository, knowledge, integrity,
 security, identity, scaffolding, and delivery capabilities with optional AgentSam/LLM composition.
-CLI/TUI surfaces make those same primitives easy to use without making a model part of the implementation.
+The interactive CLI can run the same bounded capabilities through an explicitly selected model while
+keeping model choice, reasoning effort, processing tier, credentials, approvals, context, and cost inspectable.
 
 **npm:** `@inneranimalmedia/agentsam-sdk` · **Source:** [GitHub](https://github.com/SamPrimeaux/agentsam-sdk)
 
 Node 22.5+ is required. Docker is optional for container commands. Python 3.10+ is required
-for the bundled Python repository tools; Rich is optional for the richer terminal UI.
-See the [2.0 release guide](docs/sdk-2.0-release.md) for publication status and migration notes.
+for the bundled Python repository tools. Rich is optional for the contributor-only terminal renderer lab.
+See [release receipts](docs/RELEASES.md) for publication status.
 
 ## Install
 
@@ -71,17 +72,18 @@ read-only `repository.snapshot` composition primitive. See [Capabilities and pre
 | Capability | Entry point | Guide |
 | --- | --- | --- |
 | Capability registry + presets | `agentsam capabilities`, `/capabilities`, `/presets` | [Capabilities](docs/CAPABILITIES.md) |
+| Portable AgentSam skills | `agentsam skills`; `/skills` | [Skills](skills/README.md) |
 | Canonical repository snapshot | `agentsam inspect --json`; `/repository` | [Capabilities](docs/CAPABILITIES.md) |
 | Git context and bridge client | `agentsam context --json`; `/git-context`, `/bridge-client` | [Portable context](docs/PORTABLE_CONTEXT.md) |
 | Identity contracts and adapters | `/identity`; `agentsam identity init` | [Identity](packages/identity/README.md) |
 | Repository knowledge | `agentsam index`, `search`, `repo`; `/knowledge` | [Knowledge](docs/portable-knowledge.md) |
 | File integrity | `agentsam merkle`; `/merkle` | [Merkle](docs/MERKLE.md) |
-| Dependency health and repair | `agentsam security`; `/security` | [Security](docs/SECURITY.md) |
+| Security, trust-boundary scan, and repair | `agentsam security`; `/security` | [Security](docs/SECURITY.md) |
 | Mini prototypes | `agentsam mini`; `/mini` | [Mini](docs/MINI.md) |
 | Recon bounded-worker packets | `agentsam recon pack\|validate` | [Recon](docs/RECON.md) |
 | Local containers | `agentsam dockerize`; `/dockerize` | [Dockerize](docs/DOCKERIZE.md) |
 | Background indexing service | Docker `knowledge_service`; `/knowledge-service-client` | [Knowledge service](docs/knowledge-service.md) |
-| Local status, DB, terminal UI | `agentsam status`, `db`, `tui`, `start-local` | [Terminal UI](docs/CLI_SHELL.md) |
+| Interactive Agent Sam + resumable local runtime | `agentsam`, `agentsam resume`, `whoami`, `status`, `models`, `start-local` | [CLI shell](docs/CLI_SHELL.md) |
 
 Export suffixes such as `/identity` mean imports from
 `@inneranimalmedia/agentsam-sdk/identity`. Use `agentsam <command> --help` where supported.
@@ -104,12 +106,15 @@ authorizes its caller. Other local tooling uses Node APIs.
 
 ## Host integration and ownership
 
-Deterministic SDK capabilities remain useful without a model. The root `AgentSam` helper supplies an
-optional routing/session wrapper, while model orchestration, tool execution policy, provider credentials,
-actor/account authorization, workflow durability, approvals, jobs, and production application records
-belong to the consuming host application. Git/repository identity never proves actor authority, and the SDK
-does not create a second platform tools database. The old `scaffoldProject()` export is deprecated; use
-`agentsam create` or the local scaffold commands.
+Deterministic SDK capabilities remain useful without a model. The installed CLI adds a portable local
+runtime for explicit model selection, bounded tool orchestration, secure machine-local credential lookup,
+project-scoped execution approvals, provider-neutral resumable sessions, and usage/cost receipts. Those
+local records live under the user's AgentSam home state rather than portable repository config.
+
+Production actor/account authorization, shared credential vaults, workflow durability, remote job ownership,
+and application records still belong to the consuming host. Git/repository identity never proves actor
+authority, and the SDK does not create a second platform tools database. The old `scaffoldProject()` export
+is deprecated; use `agentsam create` or the local scaffold commands.
 
 This repository owns portable code once. Applications import it and provide adapters;
 they do not mirror SDK trees. [Ownership protocol](protocol/README.md).
@@ -123,7 +128,7 @@ npm run verify:release
 
 Release verification runs Node/identity tests, bootstrap and package checks, installed
 tarball fixtures in unrelated repositories, Python tests, and a complete dependency scan.
-[Development](DEVELOPMENT.md) · [Release guide](docs/sdk-2.0-release.md) ·
+[Development](DEVELOPMENT.md) · [Release receipts](docs/RELEASES.md) ·
 [Branch archive](docs/branch-archive-2026-09-02.md).
 
 License: MIT. Optional visual experiments and host-specific integrations retain their

package/bin/agentsam

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';