sept-agent 0.1.3 → 0.1.4

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.