sept-agent 0.1.2 → 0.1.4

package/docs/architecture.md

@@ -1,168 +0,0 @@
-# SEPT module map
-
-SEPT exposes three npm entries over one runtime: `sept-agent` composes a complete worker, `sept-agent/client` is bounded HTTP transport, and `sept-agent/hands` exposes existing trusted operator configuration/filter helpers. Only those entries are consumer APIs.
-
-SEPT is organized by the mechanisms it owns. Each mechanism has one public `index.ts`; production callers outside that folder use that surface rather than implementation files. Focused tests may import an implementation directly when doing so avoids widening a runtime facade.
-
-```text
-src/
-  index.ts                       export-only root npm entry
-  hands.ts                       export-only operator npm entry
-  worker-api.ts                  shared public worker contracts/identical function binding
-  hands-api.ts                   shared public hands contracts/identical helper bindings
-  package-metadata.ts            import-safe installed package/Pi metadata
-  worker/
-    index.ts                     internal complete-composition boundary
-    worker.ts                    createWorker, bound readiness and shared idempotent stop
-    capabilities.ts              shared CLI/factory/direct policy and Pi/backend wiring
-  client/
-    index.ts                     export-only public client entry and type-only DTOs
-    client.ts                    five existing HTTP operations, stable caller IDs
-    request-codecs.ts            origin/header/identifier/page/request bounds
-    response-codecs.ts           unknown JSON, durable DTO/status/identity/cursor checks
-    transport.ts                 fetch, first abort/timeout, streamed byte bounds
-    errors.ts                    fixed safe TaskClientError classifications
-  cli.ts                         installed dispatch, argv/env/defaults/signals/telemetry
-  cli/
-    auth-interaction.ts          terminal adapter for Pi AuthInteraction
-  model-access/
-    index.ts                     intentional public surface
-    contracts.ts                 credential-blind provider/model/auth/selection DTOs
-    input.ts                     hostile-object narrowing at configuration boundaries
-    jsonc.ts                     bounded JSONC parsing for Pi models.json
-    custom-configuration.ts      endpoint, credential, and rollover-metadata safety
-    model-metadata.ts            identifiers, model limits, and built-in fallback pair
-    pod-selection.ts             atomic credential-free Pod default persistence
-    normalization.ts             credential-blind Pi metadata and error projection
-    runtime-factory.ts           validated installed Pi ModelRuntime construction
-    service.ts                   catalogue, authentication, selection, and preflight facade
-  durable/
-    index.ts                     durable state public surface
-    contracts.ts                 run, task, handover, conversation, lifecycle contracts
-    errors.ts                    classified durability and capacity failures
-    limits.ts                    queue, record, conversation, and control bounds
-    filesystem.ts                atomic files, fsync ordering, bounded JSONL scanning
-    validation-primitives.ts     shared hostile-input narrowing primitives
-    state-codecs.ts              manifest and lifecycle-snapshot codecs
-    evidence-codecs.ts           event, message, conversation, and readiness codecs
-    control-codecs.ts            assistant control and handover validation
-    lease.ts                     stable process identity and exclusive durable leases
-    run-evidence.ts              sequenced internal events and bounded lifecycle logs
-    conversation-store.ts        bounded client conversation retention and recovery
-    operator-queue.ts            exact input admission, proof, and compaction
-    context-transfer-store.ts    checkpoint and handover durability ordering
-    run-store.ts                 cohesive facade over one run's durable mechanisms
-    run-discovery.ts             fail-closed restart discovery
-    worker-lifecycle-store.ts    durable drain/readiness authority
-  ingress/
-    index.ts                     HTTP public surface
-    errors.ts                    request errors and HTTP status mapping
-    service.ts                   authenticated HTTP, model projection, replay, SSE
-    validation.ts                task/workspace validation and model preflight composition
-    webhook.ts                   normalized event validation, hashes, receipts
-    webhook-router.ts            idempotent event-to-worker routing
-  observability/
-    index.ts                     injected facade and construction surface
-    contract.ts                  business-facing observability contract
-    configuration.ts             identity, resource, exporter selection
-    logger.ts                    bounded redacted JSON stderr logging
-    safe-fields.ts               field allowlist and value bounds
-    exporters.ts                 contained exporter wrappers
-    metrics.ts                   runtime instruments and bounded state
-    setup.ts                     SDK/exporter selection and signal-owner construction
-    telemetry.ts                 facade implementation and signal lifecycle
-    tracing.ts                   spans, propagation, limits, provider
-  pi-integration/
-    index.ts                     Pi session-policy public surface
-    diagnostics.ts               non-secret installed diagnostics
-    prompts.ts                   control, continuation, handover prompts
-    rollover.ts                  adaptive arithmetic and durable evidence
-    durable-host.ts              native Harness/conversation lifetime and sanitized events
-    durable-runtime.ts           authenticated Models, registry and SQLite FULL construction
-    durable-invocation.ts        native submission/recovery and finalized-usage steering
-    durable-admission.ts         bounded captured operator IDs for native admission
-    durable-session-files.ts     strict native locators and unique successor discovery
-    durable-resources.ts         operator prompts/skills and untrusted repository instructions
-    durable-extensions.ts        bounded trusted native module loading
-    durable-tools.ts             existing Pi tools registered as native durable tasks
-    message-text.ts              text-only native response projection
-  execution/
-    index.ts                     supplied backend public boundary
-    contracts.ts                 one bounded effect/resource port and profile identity
-    profile.ts                   actual Linux isolation and mount provenance validation
-    protocol.ts                  bounded hostile request/result codecs
-    docker-backend.ts            exclusive namespace lease, live authority and joined cancellation
-    docker-engine.ts             explicit local Unix-socket Engine HTTP/exec control
-    warm-channel.ts              authenticated resident RPC and serial parent operations
-    hands-entry.ts               retained installed Pi body dispatch inside hands
-    hands-resident.ts            resident frames and operation-local effect acknowledgements
-    hands-processes.ts           guarded attachments and exact namespace lifetime
-    hands-process-owner.ts       fixed command UID and bounded descendant joins
-    hands-native-child.ts        minimal native search child streams/events over that owner
-    hands-selected-inputs.ts     opening image/sealed-host checks and exact image aliases
-    hands-resources.ts           protected authorized resource epoch view
-    native-env.ts                minimum native environment with typed unsupported operations
-  runtime/
-    index.ts                     runtime public surface
-    controller.ts               durable cycling and Pi-native cancellation state machine
-    worker.ts                   single resident slot, drain, controller ownership
-```
-
-The dependency direction is:
-
-```text
-public root / CLI worker -> worker -> ingress -> runtime -> pi-integration -> model-access
-CLI direct -----------------> worker capability helpers -> native host/backend
-public client -> HTTP -> ingress (no root/CLI/worker import)
-public hands -> existing configuration/firewall functions
-
-composition -> ingress -> runtime -> pi-integration -> model-access
- |        |                         |               |
- +--------+-------------------------+---------------+-> durable
-          +-------------------------+-----------------> observability contract
-```
-
-`model-access` is normalization and control around the installed Pi `ModelRuntime`, not another provider layer. Pi owns provider/model discovery, auth, credential storage/refresh, availability, compatible endpoint execution, and model requests. SEPT exposes only approved metadata, reads the atomic credential-free Pod default for every admission, and preflights the final pair before `RunStore.create()`. Direct and webhook tasks use the same admission function and service. Login remains UI-neutral in the service; only the installed CLI supplies an interaction adapter. Plain HTTP exposes authenticated read/selection routes but no secret mutation.
-
-`durable` has no dependency on higher mechanisms. Existing format-2 manifests with fixed rollover options remain readable and normalize to format 3; all new manifests contain the resolved provider/model and no rollover knobs or credentials. The state-root `worker-state.json` remains authoritative for accepting/draining/drained readiness. Each run's bounded `conversation.jsonl` remains the sole client-facing event contract, separate from internal lifecycle events, logs, Pi sessions, rollover evidence, and checkpoint/handover controls.
-
-`pi-integration` receives the selected Pi model from the manifest, verifies context/output metadata again, and opens the run's native Durable Harness with SQLite FULL and compaction disabled. Native conversation IDs are numeric; SEPT exposes their string form and bounded versioned locators. `rollover.json` remains scoped to provider, model, conversation identity and context window. Native finalized-response hooks supply usage; a stable steering submission is reused after restart or resumed with a distinct interrupted-handover recovery input. Handover JSON, Markdown, event and state commit before a fresh native conversation and provider UUID are created. Exact captured operator IDs accompany admission, so later queue arrivals cannot be marked in an earlier prompt.
-
-Trusted agent-directory modules follow Node process/module-URL caching: host replacement and same-process worker stop/reopen do not guarantee edited-code reload; use a fresh Node process. They register native declarative extensions, including supported tools, sections, hooks, wrappers and tasks. Project trust remains false; repository instructions do not execute plugins. The existing Pi tools are adapted into native Durable tasks with explicit replay safety and cancellation. Both their complete existing bodies and the minimum native environment operations use the consumer-supplied `execution` backend. The backend enforces effects separately from brain; Pi remains the scheduler, replay and provider owner. New runs have one engine, with no coding-agent production host or historical transcript converter.
-
-`runtime` retains execution, cancellation, wait/wake, shutdown, limits, restart adoption, and slot ownership without knowing HTTP. `ingress` translates the authenticated API and webhook contract onto runtime and model-access services. `observability` imports no business mechanisms and receives only bounded classifications/numbers; model identifiers, credentials, auth interactions, prompts, and provider errors are not telemetry fields.
-
-The architecture suite enforces index-only cross-mechanism imports. `npm run build` cleans `dist`, so deleted or moved modules cannot survive as stale executable output. SEPT does not add ACP, a second agent loop, provider client, tokenizer, compactor, dashboard, cloud service, or model server.
-
-`worker/worker.ts:createWorker` composes the authenticated service, capability admission and actual post-bind endpoint closure. The installed CLI worker calls that same factory; direct run reuses the extracted capability helpers. Library options are explicit, imports are inert, and the caller owns signals/telemetry shutdown. Ready means listener/router plus synchronous adoption, while native Pi work continues asynchronously and publishes task state. Stop reuses the durable boundary; waiting reopen preserves session and budgets.
-
-This shared composition binds the single consumer-supplied Docker Linux hands container into the installed callers. Brain retains credentials, Models/Harness and SEPT control state; hands gets namespace aliases, a clean environment and exact bounded read-only resource projections. Missing/unsupported enforcement refuses without a local fallback. The `docker-linux-warm-v1` profile uses the same finite private `/workspace` tmpfs with default file rights and explicitly granted commands. Consumers seed/export it and preserve bytes before stopping. Selected data/code may be baked read-only image trees, with genuinely `FS_IMMUTABLE`-sealed Linux host inputs retained as optional compatibility. Ordinary RO binds and private-domain RW host binds refuse. The file-only `mutable-file-bind` alternative omits command/discovery traversal and image aliases. Completed commands join namespace descendants; normal close retains the consumer-owned idle namespace. Cancellation/loss stops and verifies it before settlement, and unverified cleanup durably blocks instead of publishing cancellation. Projection refresh relies on private bounded ownership receipts; consumer markers grant no deletion authority. See [the profile contract](pi-contract.md#supplied-hands-reference-profile) and [consumer image recipe](pi-contract.md#selected-image-data-and-code).
-
-The bounded channel carries version/generation/configuration/session/sequence-correlated operation, effect check/ack and command frames. Authentication grants no rights: the live parent rechecks policy, roots, task identity, pins, expiry and cancellation at admission, immediately before effects/command start and at result acceptance. Opening qualifies immutable source/image/kernel facts; live checks retain bounded generation/mount/topology and anchored inode ownership without scanning the workspace on each call. Limits remain 512 KiB request, 4 MiB result and FIFO eight. Ordinary body errors preserve a healthy resident; broken framing/identity/cleanup seals admission and stops the exact generation before truthful settlement.
-
-## Capability policy ownership
-
-`durable/capability-policy.ts` owns the bounded private record, exact codec, fsync and revision CAS; it imports no lifecycle or execution behavior. `cli/permissions.ts` is the local operator writer; `worker/capabilities.ts` owns the shared worker/direct capability composition. `execution/capability-admission.ts` maps validated rights onto the supplied namespace and effective registrations. `DockerExecutionBackend` owns live revision/generation checks, queued/active ownership, policy-change shutdown and run binding reconciliation. `docker-control.ts` owns kernel qualification, bound lifetime receipts and exact-generation stop verification through the explicit `DockerEngineControl` Unix-socket HTTP client; `profile-configuration.ts` decodes trusted configuration while `profile.ts` validates actual kernel containment. `hands-files.ts` supplies complete supported Pi file operation seams within hands, with retained directory descriptors, independent rights and bounded regular single-link inode access.
-
-`hands-selected-inputs.ts` parses optional `imageSelected` exact `{ alias }` objects, normalizes absence to `[]` and runs opening selected-tree/image qualification from `docker-control.qualifyKernelProfile`. Image aliases use `[A-Za-z0-9_-]{1,64}`; existing host aliases retain `[A-Za-z0-9_-]+`, including longer aliases. All image/RO/RW aliases share the existing eight-unique-alias bound and policy grants. Image roots have no host source/stat/seed path. The C checker retains one descriptor-anchored bounded type/link/device/depth/count/path walk, requiring per-inode immutable flags only for the sealed-host mode. Exact image/read-only-rootfs and live image/generation/mount receipts protect baked roots; equal, ancestor and subtree mounts refuse. Configuration/data/code changes require fresh image where applicable, fresh generation and authority after quiescence. Literal `uid-dac-fixed-helper-v1` in the kernel receipt prevents old authority being silently reused; incompatible history remains intact.
-
-Policy authority never enters HTTP task/webhook/model input. Nonempty old state without policy remains dormant; malformed present state fails closed. Native Harness still owns scheduling, safe/unsafe replay and task identity; the worker still owns its single slot, drain, exact queues and budgets. Live denial wins before any queued/replayed effect, while already accepted durable inputs remain recoverable. Supported uniform-read policy retains whole native search/resource bodies. Partial-read namespaces omit search/list and workspace resource discovery; they keep independent anchored file tools and trusted global sections. There is no alternate scheduler, policy editor, provisioner or new operation journal.
-
-`hands-guard.c` is the fixed Linux constructor for trusted entry process protection. The build stage alone compiles its shared library; the runtime image contains the fixed library under its read-only root. `hands-guarded-command.ts` composes the cleared offline environment, fixed preload and disabled SIGUSR1 inspection; a fixed Node prelude verifies version-2 constructor acknowledgement before the resident starts. The resident UID10002 retains imports, private resource epoch and a correlated non-TTY RPC attachment. Commands run UID10003:GID10002 without the brain group; `/app` is UID10002:GID10001 mode 0750 and resident HOME/epoch/MIME captures are private 0700 with files 0600. Root-owned0555 command/rg/fd executables live in `/usr/local/libexec/sept`; private HOME contains matching supplied discovery aliases. The command entry establishes a separate session for the SIGCONT boundary. Fixed command/join helpers retain sole execution/descendant ownership. DAC/nondumpability/guards protect resident bytes, memory, signals, imports and control descriptors. Some public proc metadata and resident command-line correlation remain visible; correlation and command stdout cannot acknowledge or dispatch authority.
-
-Pi still owns the full grep/find bodies. The image patch adds their optional native spawn callback, bound only during the current admitted operation. `hands-command-authority.ts` reconstructs exact native argv for the matching grep→rg/find→fd parent, requires current READ authority/uniform readability, rejects private roots and supplies network:false without a new helper timer. These children consume no Bash execute grant. Fixed `/tmp` capture-name exclusions remain. `hands-native-child.ts` adapts separate bounded stdout/stderr, kill/error/close and drain behavior to the existing command owner; it is not another scheduler or process owner. Per-stream UTF-8/order survives the transport; Bash alone combines chunks in arrival order. Custom results use only stdout (4096-byte bound), with stderr drained within the shared 4 MiB output budget. Helper loss/overflow/cancellation cannot yield partial normal success; close/settlement waits for exact joins and native limit/abort conventions remain Pi-owned.
-
-Image delivery uses exactly four assets in `image/pi-native-search`: overlay, patch, provenance and README. Revision `sept-native-search-v1` overlays only `dist/core/tools/{find,grep}.{js,d.ts}` after unchanged locked `npm ci`; host Pi 1.1.0 remains stock, with the exact locked package graph. Docker verifies upstream/overlay and effective bytes before compile, after prune and after final COPY; opening qualification rechecks pinned private provenance and effective installed hashes. The pinned registry archive omits LICENSE; the existing README retains the exact upstream MIT notice and is privately copied with provenance. See [reproduction/provenance](../image/pi-native-search/README.md).
-
-
-`durable/capability-request-codec.ts` validates exact bounded operation/content and decision facts; `capability-requests.ts` persists at most 32 immutable original denials and one matching retry claim through the existing policy lease/atomic helpers. `execution/capability-requests.ts` connects those facts to live run/policy/generation checks; the Docker backend retains effect ownership, expiry timers, cancellation and namespace joins. `cli/permission-decisions.ts` owns local inspection/decision/direct retry only. Native Pi remains the sole task journal/scheduler/provider loop. Pending wait is typed by `permissionRequestId`, published after closure and cleared only by the shared explicit accepted-message wake. Recovery of an interrupted request closes the captured namespace before checkpointing input without dispatching native work. One optional operator-registered hand uses anchored hash-verified code in `execution/custom-hand.ts`, outside the protected entry and brain API.
-
-The single custom tool pins its operator path/hash/replay in native task memo evidence before execution intent. Recovery requires that original pin to be present and unchanged before effects; replacement code needs a new native task. This memo grants no permission and never resumes a denied original call.
-
-Custom code must be below an admitted RO image or genuinely sealed host alias and satisfy the existing bounded arbitrary-execution profile. Anchored code is read/hash-checked once (64 KiB maximum), then the exact bytes/input are checked again by the parent and passed to the clean Node child. Native input has text `maxLength: 256` plus a 1024-byte transport bound, optional boolean network intent, stdout-only 4096-byte/64-line native output limits and the existing 5-second timeout. SAFE replay rechecks current pin/authority; UNSAFE interrupted effects retain uncertainty without replay. No native API object or credentials cross into the child.
-
-Hands networking has two enforced layers: the consumer owns an exact IPv4/IPv6 kernel filter excluding special/metadata and all reachable public/private brain endpoints, and the resident remains socket denied while each actual command installs inherited seccomp socket denial unless explicit policy/exact approval and call intent permit network. Explicit grants include legitimate private/CGNAT/ULA peers and private DNS. Shared protected/gateway resolvers permit only UDP/TCP destination53 with complete nonconflicting protected endpoint facts. SEPT validates current brain interfaces, runtime-derived topology, DNS and actual filter tables before effects through its trusted control client; configuration fingerprints bind the complete portable consumer inventory. It does not provision a namespace or run a network broker. Native Bash/custom schemas preserve bounded network intent in operator request/retry identities; network expansion uses the existing quiescent fresh-generation rule. Credentials and Models remain brain-owned.
-
-Support is bound to the exact qualified source/image/host combination. Native Windows worker operation remains unsupported because Unix control/POSIX leases remain; Intel Mac and Windows Docker Linux/WSL recipes remain unqualified. [The repository-only historical record at d361123](https://github.com/DB-Conneely/sept/blob/d361123d7c242db5af3ae2d1cb4daea4a2acdeff/docs/as-built/capability-confinement.md) retains source/image evidence and publicIPv6/UFW/provider-outage/OAuth and unknown original stream-loss qualifications.
-
-The package ships matching source maps/source, canonical docs, notices and all four image assets. Its allowlist excludes tests/audits/private evidence/state/credentials. `prepack` reuses the existing clean/build; it adds no compiler, bootstrap, provider or provisioner. The tarball is not a complete Docker build context. [SDK ownership](sdk.md) and [the documentation index](index.md) are the consumer entry points.

package/docs/index.md

@@ -1,55 +0,0 @@
-# SEPT documentation
-
-This is the canonical Markdown corpus for people and AI assistants. Read these same files from a checkout, the npm package or a website renderer. There is no separate AI contract.
-
-## Version and support
-
-This corpus describes `sept-agent@0.1.0`, ESM on Node.js >=22.19.0, with installed Pi 1.1.0. Only `sept-agent`, `sept-agent/client` and `sept-agent/hands` are npm APIs; internal source/mechanism barrels are not public entries. CommonJS, browser use and native Windows worker operation are unsupported.
-
-Execution uses an explicitly supplied local Docker Linux Engine (API 1.44–1.52, cgroup v2) and the matching SEPT image. Installing npm does not compile the C helpers or apply the image-only overlay. Published versioned image tags select Linux AMD64 or ARM64 automatically. On macOS the Node worker runs on the host and Docker Desktop supplies Linux containers. Native Apple Silicon task execution is qualified separately; Intel Mac package install/worker lifecycle checks do not establish task/effect support. Building locally requires a pinned full source checkout; the tarball intentionally excludes the build/test context.
-
-The prior portability qualification is historical: executable source `3bf4f560e4989005469431c16a67fd911398fa01`, confirmed at docs-only commit `d361123d7c242db5af3ae2d1cb4daea4a2acdeff`. Its [repository-only as-built record](https://github.com/DB-Conneely/sept/blob/d361123d7c242db5af3ae2d1cb4daea4a2acdeff/docs/as-built/capability-confinement.md) records native abyss Ubuntu26.04.1/x86_64, kernel7.0.0-38, Docker29.1.3/cgroup v2 and Node 22.22.1; native Mac ARM qualifies only its scoped Docker Linux path. This does not certify a later package/image. Full Darwin, Intel Mac, Windows/WSL and arbitrary combinations remain unqualified. The [Pi contract qualifications](pi-contract.md#portability-qualification) retain the exact network/provider/security/evidence limits.
-
-## Developer reading order
-
-1. [README](../README.md): install, worker and client entry points.
-2. [Models](models.md): choose/authenticate a suitable model.
-3. [Pi and supplied hands](pi-contract.md#executable-supplied-hands-setup): supply the execution namespace and first-boot policy.
-4. [SDK](sdk.md): embed the worker and connect an existing service.
-5. [Worker API](worker-api.md): complete HTTP/SSE routes and durable semantics.
-6. [Architecture](architecture.md) and [observability](observability.md): ownership and operational evidence.
-7. [Contributing](../CONTRIBUTING.md): exact setup/gates and change expectations.
-
-The [Node app](../examples/node-app/README.md) hosts the worker and authors a trusted native extension. The [incident app](../examples/incident-investigator/README.md) integrates inline evidence, WAIT and later operator evidence through the public client. Use separate fresh authority roots for these different grants.
-
-## AI task navigation
-
-| Task | Read and preserve |
-| --- | --- |
-| Embed/start/stop/reopen a worker | [SDK worker lifecycle](sdk.md#worker-lifecycle); explicit roots/token and caller-owned signals/telemetry |
-| Integrate an existing HTTP service | [Five client calls](sdk.md#five-client-calls); stable IDs, ambiguous acceptance and current state |
-| Recover a conversation gap | [Finite 410 recovery](sdk.md#finite-410-recovery); report the missing evidence before choosing retained tail |
-| Select/authenticate/configure a model | [Models](models.md); immutable pair, Pi-owned credentials and declared usage/context metadata |
-| Supply hands or set rights | [Executable setup](pi-contract.md#executable-supplied-hands-setup) and [local permissions](pi-contract.md#local-hands-permissions); no task-text authority |
-| Write or port a native extension | [Native authoring](pi-contract.md#author-build-and-load-a-native-extension); normal matching imports and full brain-code trust |
-| Use SSE/drain/model routes absent from the client | [HTTP API](worker-api.md); retain all routes and bounds |
-| Diagnose state versus telemetry | [Observability ownership](observability.md#library-and-cli-ownership); durable evidence is authority |
-| Change source/API/examples | [Contribution rules](../CONTRIBUTING.md) and [architecture](architecture.md); exercise the installed production path |
-
-## Website and raw Markdown mapping
-
-A renderer can map routes directly to these source files. Links remain ordinary Markdown; publication and routing infrastructure are outside this package.
-
-| Suggested website route | Canonical file in this package |
-| --- | --- |
-| `/` | [README.md](../README.md) |
-| `/docs` | [docs/index.md](index.md) |
-| `/docs/sdk` | [docs/sdk.md](sdk.md) |
-| `/docs/models` | [docs/models.md](models.md) |
-| `/docs/worker-api` | [docs/worker-api.md](worker-api.md) |
-| `/docs/pi-contract` | [docs/pi-contract.md](pi-contract.md) |
-| `/docs/architecture` | [docs/architecture.md](architecture.md) |
-| `/docs/observability` | [docs/observability.md](observability.md) |
-| `/contributing` | [CONTRIBUTING.md](../CONTRIBUTING.md) |
-
-Repository-only rules, audits, specifications and historical as-built evidence are explicitly linked to the repository. Historical claims use pinned revisions. They are not additional files in the npm artifact.

package/docs/models.md

@@ -1,78 +0,0 @@
-# Models and Pi authentication
-
-SEPT uses the installed Pi **1.1.0 ModelRuntime**. A suitable supported/configured model can run a SEPT task; “any model” does not mean any arbitrary protocol or incomplete model metadata. Pi owns provider discovery, availability, authentication, requests and loaded local-model integrations. SEPT normalizes bounded credential-blind metadata and controls immutable task selection.
-
-## Select a model
-
-All commands below use the same explicit private agent directory as the worker:
-
-```sh
-sept auth status --provider openai-codex --agent-dir "$PI_CODING_AGENT_DIR"
-sept auth login --provider openai-codex --method subscription --agent-dir "$PI_CODING_AGENT_DIR"
-sept auth login --provider anthropic --method api-key --agent-dir "$PI_CODING_AGENT_DIR"
-sept models list --provider openai-codex --agent-dir "$PI_CODING_AGENT_DIR"
-sept models select --provider openai-codex --model gpt-6-sol --agent-dir "$PI_CODING_AGENT_DIR"
-sept models current --agent-dir "$PI_CODING_AGENT_DIR"
-sept models validate --agent-dir "$PI_CODING_AGENT_DIR"
-sept doctor --agent-dir "$PI_CODING_AGENT_DIR"
-```
-
-Login reads hidden TTY input or stdin, including secrets/manual codes; never put credentials in arguments, tasks, profiles or evidence. `sept auth logout --provider anthropic --agent-dir "$PI_CODING_AGENT_DIR"` delegates to Pi. Pi's `auth.json` retains one credential per provider and owns refresh. Keep agent storage private and outside hands; do not commit it or embed it in an image. CLI defaults use `${PI_CODING_AGENT_DIR:-~/.pi/agent}`; library callers explicitly provide `agentDir`.
-
-Each direct or HTTP/webhook task resolves:
-
-1. Its explicit complete `provider`/`model` pair.
-2. The Pod's freshly reread `sept-model.json` default.
-3. Built-in `openai-codex/gpt-6-sol`, only after Pi validates existence, availability, authentication and metadata.
-
-The fallback is not a credential/availability promise. The default record is atomic mode0600 and contains only format version/provider/model. Changing it affects later admissions; every accepted run's final pair persists immutably. `thinking` is per task: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`, default `xhigh`; suitability remains Pi/model-owned.
-
-```sh
-sept run --task "Review the evidence and state unknowns" --role "Evidence reviewer" \
-  --provider openai-codex --model gpt-6-sol --thinking xhigh \
-  --state-dir "$SEPT_STATE_DIR" --agent-dir "$PI_CODING_AGENT_DIR" \
-  --workspace "$SEPT_WORKSPACE_ROOT" --hands "$SEPT_HANDS_CONFIGURATION"
-```
-
-For the public client, put `provider`, `model`, `thinking` in `task`. Model preflight precedes durable acceptance; missing credentials or unusable metadata refuse safely. Authenticated HTTP exposes provider/model catalogue, GET selection and PUT selection for future runs; see [all routes](worker-api.md). It deliberately offers no secret-bearing login over plain TCP. Catalogue responses never expose auth values/paths, raw provider objects or headers.
-
-## Custom and local endpoints
-
-Use Pi's `models.json` under the same private agent directory. SEPT accepts at most 1 MiB of configuration and requires each custom model's explicit integer `contextWindow` **4096..10,000,000** and `maxTokens` **1..contextWindow**, with 1..1000 entries per configured model list. The current compatible APIs are `openai-completions`, `openai-responses`, `anthropic-messages` and `google-generative-ai`. Pi remains responsible for endpoint compatibility and model behavior.
-
-A deliberately keyless local HTTP example, for an already running compatible server:
-
-```json
-{
-  "providers": {
-    "local-evidence": {
-      "baseUrl": "http://127.0.0.1:8080/v1",
-      "api": "openai-completions",
-      "apiKey": "local",
-      "models": [{
-        "id": "evidence-model",
-        "name": "Evidence model",
-        "reasoning": false,
-        "input": ["text"],
-        "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
-        "contextWindow": 32768,
-        "maxTokens": 4096
-      }]
-    }
-  }
-}
-```
-
-Use real server-supported IDs/limits; this is configuration shape, not a supplied model/server. Run `sept models validate`, list that provider, then select or explicitly admit its pair. Ollama, LM Studio, vLLM and Pi's loaded llama.cpp integration can be used when the installed Pi provider/API and metadata support them. SEPT performs no serving, downloading or automatic unconfigured-server discovery; model catalogue network refresh is off by default.
-
-URLs are at most 2048 characters and may not contain userinfo, query or fragment. HTTPS is allowed. Deliberate HTTP is limited to `localhost`, `host.docker.internal`, `::1`, loopback127/8 and private IPv4 `10/8`, `172.16/12`, `192.168/16`. A generic hostname/private DNS name, CGNAT or IPv6 ULA is not automatically admitted for model HTTP. These URL rules differ from [hands network CIDR rights](pi-contract.md#explicit-hands-network). Base URL paths such as `/v1` are supported here; the task client's worker URL is origin-only.
-
-The exact non-secret plaintext API-key sentinel is **`local`**, only for a keyless deliberate local/private HTTP provider. Other API-key values and sensitive headers require Pi credential storage, environment interpolation such as `${MODEL_API_KEY}`, or an intentional `!credential-command`. Header names are bounded; authorization/API-key/token/secret/password headers always require indirection. Credential strings are1..4096 characters without controls and recognizable plaintext secret material refuses. Treat credential commands as trusted operator code. Non-sensitive literal headers remain allowed. Never log resolved values.
-
-Reachability is from the **brain process**, where Pi runs: `127.0.0.1` inside a brain container means that container, not the host/hands namespace. Configure a reachable admitted endpoint and credentials there. Granting hands network does not configure model reachability or expose credentials to tools.
-
-## Usage, context and recovery
-
-Pi must provide usable context/output metadata and finalized provider-reported assistant usage. SEPT disables auto-compaction and rotates after a durable handover according to that model's context window and observed same-conversation growth. Cumulative spend never triggers rotation; there is no local tokenizer, character-count or compaction fallback. Missing/zero/regressing finalized usage is not treated as zero; persistent unusable samples stop dispatch safely. [Pi session and rollover](pi-contract.md#session-and-rollover) specifies the exact ownership/order.
-
-A successful compatible/local or live request does not establish outage tolerance or expiring OAuth/subscription refresh resilience; those remain separately qualified in [support limits](pi-contract.md#portability-qualification).

package/docs/observability.md

@@ -1,63 +0,0 @@
-# SEPT observability
-
-SEPT emits operational telemetry without changing its durable recovery or audit records. `manifest.json`, `state.json`, `events.jsonl`, `rollover.json`, operator-message evidence, checkpoints, and handovers remain authoritative and are fsynced in their existing order. Telemetry can be sampled, dropped, unavailable, or retained for a shorter period without affecting execution or recovery.
-
-## Library and CLI ownership
-
-`createWorker({ telemetry })` accepts the public `Observability` interface. The embedding host constructs and owns that implementation and its shutdown; `worker.stop()` joins the worker's durable lifecycle but does not dispose caller-owned telemetry. Omission uses no-op telemetry. Importing `sept-agent` starts no logger/exporter or signal handler and reads no telemetry environment configuration. There is no public telemetry-construction framework in the package API.
-
-The CLI owns its environment-configured telemetry, process signals and bounded shutdown/flush. Its worker command calls the same factory with that injected facade. Environment examples below apply to the CLI; an embedding application's own telemetry construction controls its behavior. Attempt worker and application-owned telemetry/provider/listener cleanup independently so one failure cannot skip another finalizer. Durable files/events remain the recovery and audit authority even when telemetry fails or is unavailable. See [SDK lifecycle](sdk.md#worker-lifecycle).
-
-## Signals and identity
-
-- **Logs:** bounded-field Pino JSON on stderr for container-runtime collection. The exact Node SQLite experimental notice is retained as a fixed `pi.sqlite.experimental` warning during the one shared driver import; unrelated Node warnings retain their platform behavior. The original warning emitter is restored after import success or failure. The public command result remains on stdout; SEPT creates no repository log files. Logs include `service.name`, `service.version`, `service.instance.id`, `sept.worker.id`, `process.pid`, lifecycle, and active trace/span IDs where available.
-- **Traces:** OpenTelemetry spans cover worker startup/adoption, authenticated HTTP routing (including credential-blind model catalogue/selection, drain, cancel, transcript, and stream setup), task/webhook/operator routing, controller and lease ownership, Pi session open/resume/rotation/close, invocations, context/checkpoint/handover events, and terminal outcomes.
-- **Metrics:** OpenTelemetry instruments cover worker start/uptime/state, run state/outcomes/current epoch and invocation (including cancelling/cancelled), session opens, Pi invocation count/latency/failure, context pressure, operator queue depth, webhook outcomes, HTTP outcomes, exporter health, and bounded Node memory/CPU/event-loop indicators. Missing provider usage leaves context pressure absent rather than reporting a misleading zero. Adaptive rollover's detailed numeric reserves, confidence class, and decision reason remain bounded durable events; telemetry retains only context pressure and rotation outcome.
-
-`OTEL_SERVICE_NAME` defaults to `sept`. Set the bounded `SEPT_WORKER_ID` to a stable deployment identity such as `review-worker-1`; it defaults to the container hostname. `service.instance.id` is `<worker-id>:<pid>`, identifying one concrete process incarnation. For cardinality and data safety, SEPT accepts only `service.namespace`, `deployment.environment.name`, `container.name`, and `container.id` from standard `OTEL_RESOURCE_ATTRIBUTES`, with each value capped at 128 characters. A deployment can set bounded labels such as:
-
-```text
-service.namespace=agent-workers,deployment.environment.name=production,container.name=sept-review-1
-```
-
-Do not put credentials, customer data, repository paths, run IDs, session IDs, message IDs, or other unbounded values in the accepted resource attributes. SEPT deliberately omits the standard process detector because its command-argument resource field could expose `--token` values or filesystem paths; bounded process PID and runtime metrics are emitted explicitly instead. Run IDs are present only in selected logs and traces for investigation. Metrics intentionally omit run, session, message, event, and path identifiers; all metric attributes use finite outcome/state/kind sets.
-
-## OTLP configuration
-
-OpenTelemetry export is disabled unless an OTLP endpoint is configured or the corresponding exporter is explicitly selected. Pino JSON logging remains enabled unless `SEPT_LOG_LEVEL=silent` is set.
-
-```bash
-export OTEL_SERVICE_NAME=sept
-export SEPT_WORKER_ID=review-worker-1
-export OTEL_RESOURCE_ATTRIBUTES='service.namespace=agent-workers,deployment.environment.name=production,container.name=sept-review-1'
-export OTEL_EXPORTER_OTLP_ENDPOINT='http://alloy.internal:4318'
-export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
-export OTEL_TRACES_EXPORTER=otlp
-export OTEL_METRICS_EXPORTER=otlp
-```
-
-Signal-specific `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` and `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` are also supported. SEPT wires OTLP over HTTP/protobuf; gRPC and HTTP/JSON exporter selection are not supported in this tranche. The upstream OTLP HTTP/protobuf exporters honor standard endpoint, header, compression, certificate, and timeout variables. Treat `OTEL_EXPORTER_OTLP_HEADERS` as a secret and inject it at runtime; SEPT never logs it. Set `OTEL_SDK_DISABLED=true`, `OTEL_TRACES_EXPORTER=none`, or `OTEL_METRICS_EXPORTER=none` to disable export.
-
-SEPT bounds the trace batch queue to 512 spans, batches to 128, limits span attributes/events, limits metric cardinality to 64 series per instrument, and limits metric export batches to 128. These conventional controls are accepted within hard safety bounds:
-
-- `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`, `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BSP_EXPORT_TIMEOUT`
-- `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_METRIC_EXPORT_TIMEOUT`
-- `SEPT_LOG_LEVEL` (`silent`, `fatal`, `error`, `warn`, `info`, `debug`, or `trace`)
-
-Exports are batched and asynchronous, and the Pino destination has a 1 MiB in-process buffer ceiling. Export exceptions are contained; failure logs contain only the signal and outcome and are rate-limited to one per minute. Span/context instrumentation executes each wrapped SEPT operation exactly once and preserves the operation's original result or failure even if the SDK fails before or after callback entry. Startup, HTTP work, durable writes, checkpointing, wake, drain, cancellation, and conversation delivery never wait for a collector. Shutdown attempts a short bounded flush, starts signal-owner cleanup independently, and still flushes process logs when an SDK or exporter throws synchronously. Process stop, durable worker drain, and targeted run cancellation retain distinct semantics.
-
-## Collector topology
-
-A minimal container deployment needs no telemetry sidecar:
-
-1. Each SEPT container sends OTLP/HTTP traces and metrics to a host-level or central OpenTelemetry Collector or Grafana Alloy endpoint.
-2. The container runtime or Alloy tails each container's JSON stderr stream. Preserve the Pino fields rather than reparsing free text.
-3. The collector/Alloy routes traces to Tempo, metrics to a Prometheus-compatible backend, and logs to Loki. Grafana queries all three using `service.name`, `sept.worker.id`, and `service.instance.id`; trace IDs correlate a log with a trace.
-
-Use TLS and authenticated collector ingress across hosts, bind collector receivers to private networks, and restrict telemetry egress from SEPT containers to the collector. Collector retries and disk queues belong at the collector, not in SEPT. Do not make collector health a SEPT readiness dependency.
-
-Start with short operational retention (for example 7–14 days for traces/logs and 30 days for aggregated metrics), then adjust from measured incident needs and cost. Apply collector-side sampling to routine health traffic, retain failures and slow invocations, cap log ingestion, and alert on dropped exporter data. Durable run evidence follows the separate state retention/backup policy and should not be shipped as telemetry. In the production image it remains under `/state/runs`, backed by the required persistent `/state` volume; OTLP traces/metrics remain collector-bound.
-
-## Data safety
-
-Instrumentation uses an allowlist of bounded operational fields. Undefined and non-finite fields are dropped; malformed, control-bearing, or oversized string attributes become the finite `unknown` label rather than being exported. Inbound W3C `traceparent` and validated `tracestate` are propagated; no other request headers or baggage are extracted. It does not export bearer credentials or headers, webhook bodies, source/event/message IDs, task or operator text, prompts, assistant text, tool arguments/output, session IDs, session-file paths, workspace/state/agent paths, provider/model identifiers, authentication sources, auth interactions, or error messages/stacks. Exact user and validated assistant conversation evidence remains only in the bounded local `conversation.jsonl` and authenticated replay/stream endpoints. Operational telemetry records route templates, status classes, bounded lifecycle states, and outcomes, but never conversation text, SSE payloads, cancellation request bodies, or cursor/message IDs.