@kelloggt/dsh-program-agents 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,170 @@
+import type { SupervisionSettings } from './supervision.js';
+import type { EndpointNetworking, ProgramEndpointBinding, ProgramEndpointDefinition, ProgramUrlDefinition, ResolvedEndpointAddress } from './endpoints.js';
+export type { EndpointNetworking, ProgramEndpointBinding, ProgramEndpointDefinition, ProgramUrlDefinition, ResolvedEndpointAddress } from './endpoints.js';
+/** JSON is the only value boundary between a supervised process and its host. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type ProgramState = 'starting' | 'running' | 'blocked' | 'stopping' | 'stopped' | 'completed' | 'failed';
+export interface ProgramDefinition {
+    /** SDK module entrypoint. Mutually exclusive with command. */
+    entry?: string;
+    /** Trusted executable argv, passed directly to spawn without an implicit shell. */
+    command?: string[];
+    name?: string;
+    description?: string;
+    urls?: ProgramUrlDefinition[];
+    /** Named app-owned listeners; dynamic endpoints request an OS-selected port (0). */
+    endpoints?: Record<string, ProgramEndpointDefinition>;
+    /** Optional descriptor for program-owned logs; supervisor capture remains separate. */
+    logsPath?: string;
+    cwd?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    allowedCapabilities?: string[];
+    /** Trusted host policy; not permission granted by program-controlled input. */
+    supervision?: SupervisionSettings;
+}
+export interface ProgramDescriptor {
+    program: string;
+    name: string;
+    description: string;
+    command: string[];
+    urls: ProgramResource[];
+    endpoints?: Record<string, ProgramEndpointDefinition>;
+    logsPath?: string;
+    supervision?: SupervisionSettings;
+}
+export interface ProgramLog {
+    sequence: number;
+    stream: 'stdout' | 'stderr' | 'system';
+    text: string;
+}
+export interface ProgramResource {
+    id: string;
+    title: string;
+    /** Legacy literal URL, or empty for endpoint recipes (never a browser loopback fallback). */
+    url: string;
+    /** Unevaluated configured endpoint recipe, retained in descriptors and terminal snapshots. */
+    endpoint?: string;
+    path?: string;
+    /** Structured public address, present only while this generation reports a binding. */
+    address?: ResolvedEndpointAddress;
+    type?: 'ui' | 'api' | 'docs';
+    /** Documentation HTTP(S) URL or informational absolute filesystem path. */
+    docs?: string;
+    available: boolean;
+}
+export interface ProgramMessage {
+    /** The sender: parent -> inbox, or program -> parent notification. */
+    direction: 'parent' | 'program';
+    body: JsonValue;
+    at: string;
+}
+export interface ProgramSnapshot {
+    id: string;
+    generation: number;
+    program: string;
+    ownerId: string;
+    label: string;
+    name?: string;
+    description?: string;
+    command?: string[];
+    logsPath?: string;
+    supervision?: SupervisionSettings;
+    state: ProgramState;
+    status?: string;
+    pid?: number;
+    startedAt: string;
+    endedAt?: string;
+    error?: string;
+    logs: ProgramLog[];
+    resources: ProgramResource[];
+    endpoints?: ProgramEndpointBinding[];
+    messages: ProgramMessage[];
+    result?: JsonValue;
+}
+export interface ProgramEvent {
+    type: 'changed';
+    run: ProgramSnapshot;
+}
+export interface CapabilityMetadata {
+    name: string;
+    description: string;
+    inputSchema?: JsonValue;
+}
+export interface CapabilityDefinition extends CapabilityMetadata {
+    handler: (input: JsonValue, context: {
+        run: ProgramSnapshot;
+        signal: AbortSignal;
+    }) => Promise<JsonValue>;
+}
+export interface ProgramContext {
+    readonly id: string;
+    readonly generation: number;
+    readonly input: JsonValue;
+    readonly signal: AbortSignal;
+    readonly inbox: AsyncIterable<{
+        body: JsonValue;
+    }>;
+    readonly parent: {
+        send(body: JsonValue): Promise<void>;
+    };
+    status(state: 'running' | 'blocked', detail?: string): Promise<void>;
+    readonly resources: {
+        publish(resource: {
+            id: string;
+            title: string;
+            url: string;
+            type?: 'ui' | 'api' | 'docs';
+            docs?: string;
+        }): Promise<void>;
+        unpublish(id: string): Promise<void>;
+    };
+    readonly capabilities: {
+        list(): Promise<CapabilityMetadata[]>;
+        call(name: string, input: JsonValue): Promise<JsonValue>;
+    };
+    readonly models: {
+        call(input: JsonValue): Promise<JsonValue>;
+    };
+    readonly tools: {
+        call(name: string, args: JsonValue): Promise<JsonValue>;
+    };
+}
+export type ProgramMain = (context: ProgramContext) => JsonValue | void | Promise<JsonValue | void>;
+export interface StartProgramOptions {
+    program: string;
+    ownerId: string;
+    input?: JsonValue;
+    label?: string;
+}
+/** Registry is structural here to keep the shared contract independent of the runtime. */
+export interface CapabilityRegistryLike {
+    list(): CapabilityMetadata[];
+    get(name: string): CapabilityDefinition | undefined;
+}
+export interface ProgramSupervisorOptions {
+    programs: Record<string, ProgramDefinition>;
+    /** Trusted harness listener/public-address policy; programs cannot override it. */
+    networking?: EndpointNetworking;
+    capabilities?: CapabilityRegistryLike;
+    onParentMessage?: (ownerId: string, message: JsonValue, run: ProgramSnapshot, signal: AbortSignal) => Promise<void>;
+    onEvent?: (event: ProgramEvent) => void;
+    /** Observer of decoded raw output, before bounded snapshot truncation. */
+    onOutput?: (run: ProgramSnapshot, chunk: string, stream: 'stdout' | 'stderr') => void;
+    /** Synchronous credential setup before spawn; revoke is called before process cleanup. */
+    bridge?: {
+        environment(run: ProgramSnapshot, definition: ProgramDefinition): Record<string, string>;
+        revoke(run: ProgramSnapshot): void;
+    };
+    maxRuns?: number;
+    maxHistory?: number;
+    startupTimeoutMs?: number;
+    stopTimeoutMs?: number;
+    callTimeoutMs?: number;
+    /** Private capture directory; standalone supervisors default to a private temporary directory. */
+    logDirectory?: string;
+    /** Trusted host override for bundled deployments; defaults to this runtime's directory. */
+    bootstrapDirectory?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/installation.md

@@ -0,0 +1,35 @@
+# Installation and integration
+
+Current UI/runtime: see `composer-strip.md` for program_register, command/watch processes and pushed updates; installed host revision v8 adds the app bridge, structured monitoring and opt-in supervision documented in `supervision.md`. The host now mounts exact routes list/start/stop/restart/events; user messaging is removed (legacy SDK parent input remains an internal tool only). Launch descriptions persist separately from execution state.
+
+## Status
+
+Local experimental source package, not published. Targets DSH0.2.1-rc.2, Cordis4.0.5. Node22.18+ with erasable TS or precompiled JS. Build with pnpm (lockfile committed). No automatic mutation of a user's profiles, credentials, model settings or running server.
+
+## Host and web contribution
+
+Mount the built `dist/host/index.js` as a Host loader entry (see README). DSH finds the nearest package manifest, discovers `dsh.client`, and serves the lazy-CJS `dist/client.js` export. Do not mount the browser bundle itself as a host entry. The host provides `programAgents` and register/start/list/stop/restart/send/inbox_send tools. The browser contributes `conversation.input.dock`, keyed by its exact session id.
+
+The web UI uses existing DSH Connection owner authentication on exact Fetch routes `/api/programAgents/{list,start,stop,restart,events}`. The rc.2 dedicated `connection.rpc.handle` path has a provider-side `webServer` injection defect, so it is deliberately not used. Exact Fetch routes are a supported extension point, checked before the Gateway interceptor. The Gateway owns the `/api` interceptor and this plugin never replaces it. Only owner principals may list/control through the browser. Program processes receive no browser credential. Model-facing tools derive owner identity from `exec.agent`, not model arguments; direct program messages and capability calls derive it from the host run, not child-provided identities.
+
+When adding a new local plugin to an existing GUI, follow DSH's normal install/HMR lifecycle and verify the existing GUI URL after a refresh. Building this repository alone is not a claim that an already-running GUI has loaded the plugin. No replacement GUI server is needed. Repository tests mount the host in isolated Cordis and exercise the actual installed client carrier in an isolated VM; they do not install into your personal profile.
+
+## Configuration
+
+Program names select trusted definitions. `entry` should be absolute; optional `cwd`, fixed `args`, explicit `env`, `allowedCapabilities`. SDK intrinsics (inbox, parent.send, status, resources) are available without a grant. Generic host capabilities require exact named grants; `models.call` additionally requires a provider/model route; `tools.call` additionally requires exact tool names visible to the live parent. Defaults deny both.
+
+UI start endpoint delegates through the exact parent's public tool pipeline. Launching happens through the parent's `program_start`, subject to its tool policy. JS plugins can use `ctx.programAgents.adapter.start(exactLiveAgent, configuredName, input, label, signal)`; direct runtime API is trusted host code, not a public unauthenticated endpoint.
+
+Configuration has `auditDirectory`, `maxRuns`, `maxHistory`, `startupTimeoutMs`, `stopTimeoutMs`, and `callTimeoutMs`. Defaults8live/64terminal history,10sstartup,3sgrace,120scapabilitycalls. Runtime hard caps and bounded protocol are independent of configured higher-level grants. Long local-model calls may need a longer explicit call deadline. Parent/app messages and buffered standard ERROR records wake the configured supervisor (default parent); INFO/DEBUG/status and normal completion do not wake it. Synthetic failure ERROR covers uninstrumented process exits.
+
+## Supported v0.1 versus deferred
+
+Implemented: real Node process lifecycle, explicit restart/generation revocation, parent/inbox JSON, unary text model calls/usage/finish, native DSH tool policy dispatch, named capability extensions, status/logs, HTTP(S) resource links, session-scoped web controls, bounded private audit journal.
+
+Also implemented: opt-in bounded restart/startup/archive admission, configured supervisor children through normal delegation, standard JSONL monitoring, MCP-shaped tool discovery/calls, managed inbox settlement with fenced lease renewal, durable schema-validated agents.ask responses, and policy-scoped implicit child creation for Agent send/ask. Deferred: token streaming SDK, unrestricted program-spawned children, native program-as-LLM-subagent-tree membership, Python, iframe dashboard embedding, automatic proxy/tunnels, arbitrary app-state restore/external-effect replay, external persistent agent services. These are deliberately not represented by fake working APIs.
+
+## Recovery
+
+Parent Agents are captured exactly, not looked up by id alone for authority. Disposal revokes the owner and stops owned programs, including racing restart. Parent turn completion does not revoke runs. Plugin unload stops all runs and closes its journal. A process crash marks links unavailable. Old-generation messages/controls cannot affect a new run. A failed hard shutdown prevents restart rather than allow overlap.
+
+Programs own durable storage and effect deduplication. DSH plugin audit is diagnostic/reconstructable model call evidence only; it does not restore in-memory programs after host restart. Unknown outcomes require external verification.

package/docs/log-format.md

@@ -0,0 +1,102 @@
+# Versioned structured JSONL logging and monitoring
+
+## Wire standard v1
+
+A log is UTF-8 JSON Lines: exactly one JSON object per newline. The standard base is:
+
+```ts
+interface StandardLogRecord {
+  timestamp: string; // ISO/RFC3339 date-time with timezone
+  level: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR';
+  log_type: string;
+  message: string;
+  operation_id?: string;
+  event_id?: string;
+  error?: { name: string; message: string; stack?: string;
+            code?: string | number; fingerprint?: string };
+  data?: JsonValue;
+  fatal?: boolean;
+  [extension: string]: unknown; // finite JSON values only
+}
+```
+
+`log_type` identifies an immutable, versioned semantic payload schema, not severity. Examples: `dsh.program.error.v1`, `dsh.http.request.v1`, `com.example.inventory.sync.v1`. Use a lowercase dotted namespace ending in `.vN`, with N a positive integer; applications should use their own reverse-DNS prefix. Schema changes require a new version, never reinterpret the same name. The `dsh` namespace is reserved for core contracts.
+
+`parseLogLine(line, registry?)` returns a valid record or `undefined`. It rejects malformed JSON, invalid base fields, lines over 64 KiB (UTF-8 bytes), nesting deeper than 32, non-finite numbers and invalid **known** payloads. Unknown correctly namespaced/versioned types are accepted when the base and JSON are valid. Unknown extension fields are allowed. Runtime JSON validation rejects loss-prone direct callers (`undefined`, Date/class instances, sparse arrays, cycles). ERROR detection uses `level === 'ERROR'` under **any** log type. `fatal` and `data.unhandled` are optional advisory metadata, not prerequisites for reporting. Batch records themselves are not fed back into error monitoring.
+
+The standalone base [JSON Schema](../schemas/standard-log-record.v1.schema.json) describes the full record. The other schemas describe only the `data` payload:
+
+| Type | Data contract |
+| --- | --- |
+| `dsh.program.error.v1` | Optional extensible object ([schema](../schemas/dsh.program.error.v1.schema.json)); errors may also omit `error`. |
+| `dsh.http.request.v1` | Required `method`, `path`, `status` (100–599); optional nonnegative `duration_ms`; extensions allowed ([schema](../schemas/dsh.http.request.v1.schema.json)). |
+| `dsh.program.error-batch.v1` | Required scoped `key`, `groups`, total `count`, timestamp `range`, `dropped` ([schema](../schemas/dsh.program.error-batch.v1.schema.json)). |
+
+`LogSchemaRegistry.register(logType, payloadSchema, {optional?})` validates known payloads without heavyweight dependencies. Registering an identical schema again is allowed; replacing a schema throws. `get()` returns a copy. Supported JSON Schema subset: type, properties, required, additionalProperties, items, enum, const, oneOf, min/maxLength, minimum/maximum, min/maxItems, pattern and descriptive metadata. Unsupported keywords fail registration rather than silently weakening validation. A new registry has no core definitions; use `defaultLogRegistry` for built-ins or register the exported core payload schemas explicitly. Schemas are trusted host/app configuration, not log-provided instructions.
+
+## Application logger
+
+Register global handlers explicitly with `installGlobalErrorHandlers(logger,{timeoutMs:500})` (exported by `/monitoring` and `/app`). It logs one standard fatal ERROR for uncaught exceptions/rejections, attempts a bounded flush, then exits nonzero. It never swallows a corrupted process or resumes execution. Disable by calling the returned disposer during orderly shutdown; do not register duplicate global handlers. The host also emits a synthetic process ERROR on nonzero exit, covering uninstrumented programs. A watched worker's fatal ERROR is monitored even when its watcher remains alive.
+
+```ts
+import { createLogger } from '@kelloggt/dsh-program-agents/monitoring';
+const logger = createLogger({ logsPath: './logs', stdout: true, private: true });
+logger.info('request complete', { method: 'GET', path: '/health', status: 200 },
+            { log_type: 'dsh.http.request.v1', operation_id: 'request-42' });
+logger.error('inventory sync failed', { warehouse: 'west' }, {
+  log_type: 'com.example.inventory.sync.v1', error: new Error('timeout'), fatal: false,
+});
+await logger.flush();
+await logger.close();
+```
+
+Exports: `createLogger(options?)`, `StructuredLogger`, `.debug/info/warn/error(message, data?, metadata?)`, `.record(fullRecord)`, `.flush()`, `.close()`. Methods synchronously validate/enqueue and return the emitted record. `warn` emits `WARNING`. ERROR defaults to `dsh.program.error.v1`; other convenience methods default to `dsh.program.log.v1`. Metadata can provide namespaced type, operation ID, event ID, normalized Error, timestamp and JSON extensions. `record` preserves the supplied severity. A new event ID is generated when absent, and both stdout and file receive exactly the same bytes/event ID. Callers can use it to suppress duplicate transport observations.
+
+Default output is stdout; file output is opt-in. `logsPath: './logs'` writes `./logs/app-log.jsonl`; alternatively set `file` to an exact filename (not both). `stdout: false` enables file-only logging. `stdout` may also be a Writable for embedding. Rotation occurs at a UTC day boundary or before exceeding `maxBytes` (default 10 MiB); `maxFiles` defaults to five **total**, active file plus `.1` through `.4`, newest first. One valid record may exceed a configured tiny rotation size but never 64 KiB. Set `private: true` for 0700 newly created directories/0600 active files. File writes are serialized, handles closed after each write, and errors surface from flush/close. Existing directory permissions are not changed.
+
+Stdout respects write callbacks/backpressure through one serialized writer; its queue is bounded (`maxQueueBytes`, default 1 MiB). Overflow throws rather than silently dropping or accumulating unbounded promises. Flush before producing more. Caller-owned stdout is not ended on close. File is written before stdout so a blocked stdout does not prevent the current record reaching the file.
+
+Common credential keys are recursively redacted, case/separator-insensitively, including password/passphrase, secret/client secret, API/private keys, access/refresh/ID tokens, authorization, cookies and credentials. **All header objects are redacted**, not merely Authorization. Redaction also applies to extensions and error metadata. This is defense in depth: arbitrary free-text messages, URLs, error stacks and unusual key names can still contain secrets; never supply credentials in them.
+
+The deterministic SHA-256 error fingerprint covers `[log_type, message, error.name, error.message, error.code]`. It excludes timestamp, stack, event ID, source and arbitrary data. Incoming fingerprint claims are not trusted for grouping. Errors without an `error` object are still reported and grouped; the logger creates a normalized error object for ERROR convenience output.
+
+## Parent-owned ErrorBuffer
+
+```ts
+const buffer = new ErrorBuffer({
+  key: `${ownerId}:${programName}`, // stable across runs, scoped to parent+program
+  directory: monitoringStateDirectory,
+  deliver: async (batch, signal) => { /* route and await actual accepted receipt */ },
+  bufferMs: 1000, cooldownMs: 30_000, maxBatch: 20,
+});
+await buffer.ready;
+buffer.add(record, { path: logPath, offset: byteOffset,
+                     run: { id: runId, generation: 1 } });
+await buffer.checkpoint(); // input durable, without forcing delivery
+await buffer.flush();      // force buffer window, preserve fingerprint cooldown
+await buffer.close();      // capture stop errors, bypass cooldown, bounded final delivery
+```
+
+This module does not choose supervisor agents or launch LLM calls. The parent supplies the delivery callback and routing policy. Use a distinct stable `key` per owner+program, and instantiate saved keys at startup to drain persisted work even if a program is not restarted. One live writer owns each key; a second concurrent instance for the same key is unsupported.
+
+Only valid ERROR records enter. Repeated event IDs (stdout plus file, or replay) are suppressed for 24 hours with a bounded 4096-entry cache. Without event IDs, equal fingerprints group as occurrences rather than pretending exact-once deduplication. Different occurrences of the same fingerprint increment counts/ranges. Normal delivery waits one second; after a delivery batch is queued, repeated fingerprints are retained until their 30-second cooldown expires, not silently discarded. `flush` makes ordinary groups eligible immediately but preserves cooldown. Shutdown turns all remaining groups into durable outbox batches and allows at most 100 ms for final callbacks; unresolved deliveries stay on disk.
+
+Batches are full standard ERROR records with `log_type: 'dsh.program.error-batch.v1'`, unique stable `event_id`, and data containing:
+
+- `key`, total occurrence `count`, first/last timestamp `range`, and capacity-loss `dropped`;
+- at most 20 `groups`, each with fingerprint, count, representative redacted `sample`, range, and optional `{path, offset, run}` source;
+- at most 64 KiB total encoded batch. Large samples are reduced to identity/message/error fields (payload/stack/extensions omitted) rather than copying a large log payload into every notification.
+
+Pending groups, dedup IDs, cooldowns and outbox are atomically replaced in a private per-key JSON state file; writes fsync before replacement. `checkpoint`/`flush` surface filesystem/load failures. Malformed state is not overwritten silently. Successful callback receipt removes a batch only after delivery; rejection/deadline retains it and retries (`retryMs`, default 1 s). The delivery timeout defaults to 10 s (`deliveryTimeoutMs`) and an optional AbortSignal lets cooperating hosts cancel. Close aborts the current callback and bounds final attempts. Each buffer retains exactly one real callback resource slot until that callback actually settles, even after a deadline or cancellation. Retries/flushes cannot launch overlapping replacement callbacks while that slot is occupied; the outbox remains durable. Noncooperative callbacks can continue externally but cannot accumulate unbounded parallel work or prevent bounded close. Once the callback settles, normal retries resume with the same batch event ID.
+
+The outbox is bounded (`maxOutboxBytes`: default 1 MiB; `maxOutboxBatches`: 64); pending groups default to 200. Async ingress is bounded to twice the pending-group limit. Overflow evicts oldest work and records occurrence loss in `dropped`; add returns false on ingress overflow/disabled/invalid records. Loss counts persist and appear in the next emitted batch. This is bounded **at-least-once**, not exactly-once: an interrupted acknowledgment may replay the same batch event ID. The recipient should persist an acceptance receipt keyed by event ID. Disk failure/power loss before checkpoint is not a durability acknowledgment.
+
+## Tail-able files
+
+`LogTailer` (alias `JsonlMonitor`) accepts `{logsPath, onRecord, readExisting?, pollMs?, run?, cursorPath?, onError?}` and exposes `.ready`, `.poll()` and `.close()`. A directory follows its `app-log.jsonl`; an explicit file path follows that file. An absent path ending in `.jsonl` is treated as a file, otherwise as a directory. Prefer existing paths or `.jsonl` filenames to avoid ambiguity.
+
+By default existing content is skipped (initial EOF) to prevent historical alert replay. `readExisting: true` starts at byte zero. Files created after attachment start at byte zero. Attach and await `.ready` **before launching** the process to capture immediate current-run file errors while keeping historical replay disabled. Stdout capture may independently ingest errors before file attachment.
+
+Reads are bounded to 64 KiB chunks and 512 KiB per poll, never full-file reads; partial lines retain at most 64 KiB. Oversized/malformed lines are ignored until a newline. A 250 ms default timer is acceptable file following, not UI polling. Inode changes drain the old open inode before attaching its replacement; shrinking files reset the decoder/offset for copy-truncate rotation. A truncate-and-regrow that exceeds the previous size entirely between observations cannot be reliably detected using stat alone. Renamed old-file late writes after switching are not followed indefinitely.
+
+Optional `cursorPath` atomically persists completed-line offsets by inode/device. On restart matching cursors resume rather than initial-seeking EOF. Callback promises are awaited before cursor advancement: when feeding a durable ErrorBuffer, call `add`, then return/await `buffer.checkpoint()` from `onRecord`. Callback failure replays the bounded uncommitted chunk; persisted event IDs suppress duplicate observations. Invalid lines can advance cursors. Partial lines never do. Cursor files contain only pointers, not records; the buffer's durable pending/outbox owns delivery. Close does a final bounded poll, clears timers, closes handles and awaits callbacks. Close the tailer before the buffer so final file errors are captured.

package/docs/publishing.md

@@ -0,0 +1,45 @@
+# Publishing to npm
+
+The package name is `@kelloggt/dsh-program-agents`. Publishing requires an npm account with access to the `@kelloggt` scope. The package is configured for public access. The first publish creates the package on npm; there is no separate package-creation step on the website.
+
+For interactive publishing, enable **two-factor authentication (2FA)** on your npm account before the first release. On npmjs.com, open **Account → Two-Factor Authentication → Enable 2FA**; a passkey or Touch ID can serve as your security key. npm requires account 2FA or a granular access token with bypass 2FA enabled. A successful CLI login alone does not satisfy this publishing requirement. See npm's [2FA setup instructions](https://docs.npmjs.com/configuring-two-factor-authentication/).
+
+## Build and inspect the release
+
+From the repository root, with Node.js 22.18+ and pnpm 10 installed:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm release:pack
+```
+
+The `prepack` hook runs `pnpm check`: the build, reference typecheck, and test suite. A failure stops packaging. The archive is saved in `.state/npm-release/`, with its name and version taken from `package.json`. Consumers receive compiled JavaScript and declarations; installation from npm doesn't run the build.
+
+Inspect the resulting archive and preview publishing it:
+
+```sh
+pnpm release:inspect
+pnpm release:publish:dry-run
+```
+
+It should contain `dist/host/index.js`, `dist/client.js`, the SDK and runtime exports, `cordis.patch.yml`, and `skills/program-agents/SKILL.md` with its supporting files. Local installation history, test records, logs, and credentials are excluded from the package.
+
+The publishing dry run skips Git checks so it can preview uncommitted work. The actual publishing command keeps pnpm's normal Git checks enabled.
+
+Test the archive in a disposable DSH profile before publishing. Installing it with `dsh plugin --profile web add /absolute/path/to/the/archive.tgz` enables the plugin through its bundle patch. Install the skill as described in the README.
+
+## Publish the verified archive
+
+Sign in and publish the same archive you inspected:
+
+```sh
+pnpm release:login
+pnpm whoami --registry=https://registry.npmjs.org/
+pnpm release:publish
+```
+
+The username check should print `kelloggt` for this personal scope. Follow any authentication prompts from npm. Publishing uses the existing archive without rebuilding it. After the first release succeeds, remove the pending-release wording from the README and make npm installation the default. For future releases, update the package version and run `pnpm release:pack` again; the scripts select the matching archive automatically.
+
+If publishing fails with **E403: Two-factor authentication or granular access token with bypass 2fa enabled is required**, check your account's 2FA settings. After enabling 2FA, run `pnpm release:login` again and retry `pnpm release:publish` in an interactive terminal. The authentication error does not require rebuilding the archive. If your configured method uses an authenticator code, you can pass it directly with `pnpm release:publish --otp=YOUR_CURRENT_CODE`; the release script forwards that option to pnpm.
+
+See pnpm's [packing](https://pnpm.io/10.x/cli/pack) and [publishing](https://pnpm.io/10.x/cli/publish) documentation.

package/docs/supervision.md

@@ -0,0 +1,73 @@
+# Supervision and ordinary app integration
+
+## Settings
+
+`program_register` and trusted configured definitions accept:
+
+```json
+{
+ "supervision": {
+  "restart": "on-failure",
+  "maxRestarts": 3,
+  "restartDelayMs": 1000,
+  "startAtStartup": true,
+  "supervisor": {"mode":"dedicated-child", "prompt":"Investigate failures and coordinate with parent; don't blindly retry external writes."},
+  "errors": {"enabled":true,"bufferMs":1000,"maxBatch":20,"cooldownMs":30000}
+ },
+ "access": {
+  "tools":["working_directory","inventory.lookup"],
+  "mcp":[{"server":"inventory","tools":["lookup"]}],
+  "messaging":true
+ }
+}
+```
+
+Defaults: restart never, no startAtStartup, supervisor parent, ERROR monitoring on. restart also accepts always (on natural success/failure, not explicit Stop). Restarts have exponential delay capped5minutes and a bounded budget (default3; max100). Budget is in-memory per host lifetime/manual start, not perpetual service management. Manual Stop cancels pending recovery in this host lifetime; persisted startup configuration is not silently rewritten. Explicit Start resets recovery budget. Process-group closure must be proven before restart. No individual DSH tool/MCP/message/external side effect is automatically retried.
+
+Supervisor modes:
+- **parent**: wakes/steers exact live owner; cold Session resolved through existing DSH SessionController when necessary.
+- **dedicated-child**: creates a real adjacent DSH subagent via parent's public subagent tool, saves its identity, then sends future reports through normal continuable messaging. Missing/non-continuable child is replaced; transport rejection does not silently reroute to someone else.
+- **new-child**: creates a fresh child per explicit notification/error batch, not per log line. Normal inherited parent model/depth/permissions and subagent capacity apply. Do not enable noisy new-child routing without sensible buffer/cooldown.
+
+`program.supervisor.send(body,{correlationId})` and `sendSupervisor(body)` select this route. Receipt accepted is inbox/delegation acceptance, not processing completion. Structured ERROR reports are buffered and delivered through the same router automatically. Parent notification source is attributed program data, never trusted instructions. Separate human-facing message UI is intentionally absent.
+
+## Start at startup and archive safety
+
+Registered launch descriptions persist in private parent-scoped catalog files; running execution does not. Once workspace/archive and SessionController services are available on DSH/plugin startup, opted-in entries are scanned. A missing live parent is resolved from its actual persisted Session with the recorded composition/model; no new unrelated root Agent is fabricated. Start runs under this parent's public program_start tool policy. Missing or archived Sessions are skipped/refused, not recreated. Session creation also checks opted-in entries, with reentrant duplicate-start guards.
+
+Program activity participates in DSH archive admission: archive without stopActivity refuses while work is running; archive with stopActivity stops this parent's process groups and cancels restart timers. Every delayed restart checks current archive status again. Defaults do not change existing registrations. Startup means DSH/plugin service startup while its process is running—not launchd/macOS boot when DSH itself isn't running. A live main/chat turn isn't required; same persisted Session ownership is.
+
+## App library
+
+```ts
+import {connectProgram} from '@kelloggt/dsh-program-agents/app';
+const program=connectProgram({logger:{logsPath:'./logs',stdout:true,private:true}});
+program.logger.info('ready',{}, {log_type:'com.example.app.ready.v1'});
+await program.supervisor.send({type:'work-ready',count:3},{correlationId:'batch-42'});
+await program.inbox.receive({waitMs:25000,leaseMs:60000},async(item,{signal})=>{
+  await processIdempotently(item.id,item.body,{signal}); // library renews/ACKs/NACKs
+});
+const text=await program.agents.ask({name:'Reviewer'},{type:'review'}); // string response
+const {tools}=await program.tools.listTools();
+const result=await program.tools.callTool({name:'inventory.lookup',arguments:{sku:'A1'}});
+```
+
+Per-run/generation bearer credentials are injected into supervised command and SDK processes, inherited by watcher workers, and revoked on stop/crash/restart. Bridge is a separate loopback127 ephemeral HTTP endpoint, not a replacement GUI server. Browser origin/ambient cookies are not admitted; Host, body, header, concurrency and deadlines bounded. Calls include no caller-selected owner/run identity. Cancellation/revocation doesn't promise external effects were rolled back. Native trusted code is still not a sandbox.
+
+Methods: tools.listTools/callTool (official MCP tool parameter/result shapes), mcp.forServer(server).listTools/callTool, agents.list/get/send/ask/request/cancel, supervisor.send/sendSupervisor, managed inbox.receive(options,handler), models.declare/list/resolve/call, conversations.open/get/list and conversation history/send/ask/events/interrupt. Named model slot defaults/descriptions and user overrides are separate from parent/global selection; explicit native routes remain callable. See the skill's models and chat-sidebar guides for configuration and copyable React/Hono UI. Tool access is limited to existing DSH tools registered through the normal DSH tool API and connected MCP tools. Exact access.tools and access.mcp grants and normal parent visibility/policy apply. Agent messaging requires explicit messaging grant and sees only parent + direct children; send/ask support explicit named get-or-create or fresh child selection under the normal parent delegation tool. SDK named capabilities remain supported.
+
+`agents.ask` defaults to a string response or accepts strict Draft2020-12 responseSchema / typed responseType helper. Requests live in private requests.sqlite; assignment precedes dispatch, one valid reply is atomically accepted through program_reply, and conflicting/late/wrong-Agent replies reject. No guaranteed Agent liveness or automatic message/delegation retry. Stable requestId keys deduplicate only within retained storage; changed inputs reject. Result reads/cancel expose known/unknown outcomes and survive host restart without redispatch.
+
+Inbox SQLite contains accepted/claimed/acked messages; namespace owner+program survives worker/host restart. Lease token + current authoritative claimant run/generation are mandatory for ACK/NACK. Claims expire or release on revoke. Managed receive renews leases, awaits handlers and owns ACK/NACK; lost ACKs raise SettlementUnknownError without unsafe retries. Cancellation aborts handler signal but cannot force noncooperative JS to stop; slots remain retained until actual settlement, renewal stops at the bounded processing deadline, and expired work can redeliver. At-least-once delivery requires app idempotency; ACK is not a distributed transaction. Poll receive bounds30s, lease5min, queue/receipts/bytes bounded. Retained receipt state is not eternal.
+
+Read the skill's [inbox guide](../skills/program-agents/inboxes.md) for examples and use cases. `examples/inbox-worker.ts` is a real no-IPC ordinary command example; build ships dist/examples/inbox-worker.js. `docs/log-format.md` and schemas define structured logger/error pipeline.
+
+## Privacy, durability and bounds
+
+Private catalog/audit sibling state contains inboxes.sqlite, supervisors/ (dedicated-child identities and acceptance receipts), error-outbox/ (pending/grouped reports and tail cursors). Never commit task data or credentials. ERROR buffering batches max20groups64KiB, dedup event_id24h bounded4096, persists1MiB64batch default bound. Capacity eviction increments dropped; filesystem errors aren't durability acknowledgements. Receipts dedup accepted batch event_ids up to4096files; budget exhaustion refuses new receipts until explicitly archived. A crash between Agent acceptance and receipt persistence may duplicate delivery: no exactly-once claim.
+
+App logger redacts known secret keys/headers but free text/stack/URLs still require care. Logs and forwarded external content must not redefine host policy. Log listeners attach before launch and use durable cursor+checkpoint to avoid acknowledged-file offsets ahead of persisted error state. Host output capture and app JSONL are distinct; stdout is parsed only when it follows the standard.
+
+## Verified scope
+
+Real process integration verifies automatic standard ERROR wakeup to parent adapter, DSH tool/MCP grant checks and exact parent tool call, durable reply/ACK, bounded process restart and cold-start archive exclusion. Real HostConnection/browser carrier regression remains. Supervisor routing tests use real routing code with mocked delegation/message service to avoid spending model tokens on synthetic errors. No live subscription inference or actual external MCP server was invoked for testing.

package/examples/dashboard.ts

@@ -0,0 +1,31 @@
+import { createServer } from 'node:http';
+import type { ProgramContext } from '@kelloggt/dsh-program-agents/sdk';
+
+/** Normal Node code: owns its state; DSH owns observation/control. */
+export default async function main(ctx: ProgramContext) {
+  let processed=0;let lastInput:unknown=null;
+  const server=createServer((req,res)=>{
+    if(req.url!=='/'){res.writeHead(404);res.end();return;}
+    // JSON text rendered via textContent, never interpolated as HTML.
+    const data=JSON.stringify({processed,lastInput,generation:ctx.generation}).replaceAll('<','\\u003c');
+    res.writeHead(200,{'Content-Type':'text/html; charset=utf-8','Content-Security-Policy':"default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'",'Cache-Control':'no-store'});
+    res.end(`<!doctype html><title>Program dashboard</title><style>body{font:18px system-ui;max-width:700px;margin:3rem auto;background:#15171c;color:#eee}pre{white-space:pre-wrap}</style><h1>Supervised program</h1><p>Reload to see the latest state. Send JSON from DSH.</p><pre id="data"></pre><script>document.getElementById('data').textContent=JSON.stringify(${data},null,2)</script>`);
+  });
+  await new Promise<void>((resolve,reject)=>{server.once('error',reject);server.listen(0,'127.0.0.1',()=>resolve());});
+  const address=server.address();if(!address||typeof address==='string')throw new Error('No server address');
+  await ctx.resources.publish({id:'dashboard',title:'Program dashboard',url:`http://127.0.0.1:${address.port}/`});
+  await ctx.status('running','Dashboard ready; waiting for JSON input');
+  try {
+    for await(const message of ctx.inbox){
+      lastInput=message.body;processed++;
+      if(message.body&&typeof message.body==='object'&&!Array.isArray(message.body)&&message.body.action==='help'){
+        await ctx.status('blocked','Waiting for supervisor advice');
+        await ctx.parent.send({type:'needs_help',reason:'Example explicit escalation',processed});
+      } else {
+        await ctx.status('running',`Processed ${processed} message(s)`);
+        console.log(`Processed message ${processed}`);
+      }
+    }
+  } finally { await new Promise<void>(resolve=>server.close(()=>resolve())); }
+  return {processed};
+}

package/examples/dsh-web-local.patch.yml

@@ -0,0 +1,15 @@
+# Local-checkout install: merge into the EXISTING web profile, do not replace it.
+# Update these absolute paths on another machine.
+- insert:
+    - id: program-agents-strip-v5
+      name: /Users/timkellogg/code/dsh-program-agents/dist/host/installed-v5.js
+      config:
+        programs:
+          dashboard:
+            name: Dashboard
+            description: Small supervised dashboard example
+            entry: /Users/timkellogg/code/dsh-program-agents/dist/examples/dashboard.js
+            cwd: /Users/timkellogg/code/dsh-program-agents
+            allowedCapabilities: []
+        maxRuns: 8
+        maxHistory: 64

package/examples/dynamic-server.ts

@@ -0,0 +1,13 @@
+import {createServer}from'node:http';
+import {connectProgram,installGlobalErrorHandlers}from'@kelloggt/dsh-program-agents/app';
+const app=connectProgram();installGlobalErrorHandlers(app.logger);
+const startedAt=new Date().toISOString();
+const server=createServer((req,res)=>{
+ if(req.url==='/api/status'){res.writeHead(200,{'content-type':'application/json','cache-control':'no-store'});res.end(JSON.stringify({pid:process.pid,startedAt,message:'Harness endpoint is bound and advertised'}));return;}
+ if(req.url!=='/'){res.writeHead(404);res.end();return;}
+ res.writeHead(200,{'content-type':'text/html; charset=utf-8','cache-control':'no-store','content-security-policy':"default-src 'none'; style-src 'unsafe-inline'"});
+ res.end('<!doctype html><title>Dynamic endpoint demo</title><style>body{font:18px system-ui;max-width:700px;margin:4rem auto}a{color:#368}</style><h1>Dynamic endpoint demo</h1><p>This server uses a harness-supplied interface and an OS-assigned port. Restarting resolves the endpoint again.</p><a href="/api/status">API status</a>');
+});
+const listener=await app.endpoints.listen('web',server);
+app.logger.info('Endpoint ready',{port:listener.port,bind_host:listener.host,local_url:listener.localUrl},{log_type:'com.example.endpoint.ready.v1'});
+let closing=false;for(const signal of ['SIGINT','SIGTERM']as const)process.on(signal,()=>{if(closing)return;closing=true;void listener.close().finally(()=>app.logger.close()).finally(()=>process.exit(0));});

package/examples/inbox-worker.ts

@@ -0,0 +1,17 @@
+import{connectProgram,installGlobalErrorHandlers}from'@kelloggt/dsh-program-agents/app';
+const program=connectProgram({logger:{logsPath:'./logs',stdout:true,private:true}});
+installGlobalErrorHandlers(program.logger);
+program.logger.info('Inbox worker ready',{pid:process.pid},{log_type:'com.example.inbox.ready.v1'});
+const abort=new AbortController();for(const signal of ['SIGINT','SIGTERM']as const)process.on(signal,()=>abort.abort());
+try{
+ while(!abort.signal.aborted){
+  await program.inbox.receive({waitMs:25000,leaseMs:60000,signal:abort.signal},async(message,{signal})=>{
+   signal.throwIfAborted();
+   // Validate the app payload and commit idempotent effects before returning.
+   // Managed receive renews the lease and ACKs success / NACKs rejection.
+   program.logger.info('Received application work',{message_id:message.id},{log_type:'com.example.inbox.processed.v1',operation_id:message.correlationId??message.id});
+   return 'processed';
+  });
+ }
+}catch(error){if(!abort.signal.aborted){program.logger.error('Inbox worker failed',{}, {error:error as Error});throw error;}}
+finally{await program.logger.close();}

package/examples/model-slots.ts

@@ -0,0 +1,12 @@
+import{connectProgram,installGlobalErrorHandlers}from'@kelloggt/dsh-program-agents/app';
+const dsh=connectProgram({logger:{logsPath:'./logs/model-slots',stdout:true,private:true}});
+installGlobalErrorHandlers(dsh.logger);
+await dsh.models.declare({
+ 'smart-model':{description:'Difficult judgments and multi-step planning.',default:{provider:'codex',model:'gpt-6.1-sol',reasoningEffort:'xhigh'}},
+ 'cheap-local':{description:'Private, low-cost classification and short summaries.',default:{provider:'local-mlx',model:'Qwen3.8-27B-4bit'}},
+});
+dsh.logger.info('Model slots ready; configure selections with the program Models button',{}, {log_type:'com.example.models.ready.v1'});
+// Declaration/configuration does not make an inference call or create a child.
+const stop=new AbortController();for(const signal of ['SIGINT','SIGTERM']as const)process.on(signal,()=>stop.abort());
+await new Promise<void>(resolve=>{const timer=setInterval(()=>{},60000);stop.signal.addEventListener('abort',()=>{clearInterval(timer);resolve();},{once:true});});
+await dsh.logger.close();

package/examples/standalone-supervisor.ts

@@ -0,0 +1,14 @@
+import { resolve } from 'node:path';
+import { ProgramSupervisor } from '@kelloggt/dsh-program-agents/runtime';
+
+const supervisor=new ProgramSupervisor({
+  programs:{dashboard:{entry:resolve('examples/dashboard.ts'),allowedCapabilities:[]}},
+  onParentMessage:async(_owner,body)=>{console.log('Program asks parent:',body);},
+});
+const run=await supervisor.start({program:'dashboard',ownerId:'demo',input:null});
+console.log('Started',run.id,'— press Ctrl+C to stop.');
+const timer=setInterval(()=>{
+  const r=supervisor.get(run.id,'demo');for(const resource of r.resources)if(resource.available)console.log('Dashboard:',resource.url);
+},3000);timer.unref();
+await supervisor.send(run.id,'demo',{hello:'world'});
+process.once('SIGINT',()=>{clearInterval(timer);void supervisor.dispose().then(()=>process.exit(0));});

package/examples/watch-server.ts

@@ -0,0 +1,12 @@
+import {createServer} from 'node:http';
+// Ordinary command program: no SDK or IPC required. Node --watch owns reload.
+const message='Watch mode reloaded successfully';
+const server=createServer((req,res)=>{
+ if(req.url==='/api/status'){res.writeHead(200,{'content-type':'application/json','cache-control':'no-store'});res.end(JSON.stringify({message,pid:process.pid,startedAt}));return;}
+ if(req.url!=='/'){res.writeHead(404);res.end();return;}
+ res.writeHead(200,{'content-type':'text/html; charset=utf-8','cache-control':'no-store','content-security-policy':"default-src 'none'; style-src 'unsafe-inline'"});
+ res.end(`<!doctype html><title>Watch demo</title><style>body{font:18px system-ui;max-width:700px;margin:4rem auto;background:#17191d;color:#eee}a{color:#9bc8ff}</style><h1>Watch demo</h1><p>${message}</p><p>Edit this file; Node reloads the server automatically.</p><a href="/api/status">API status</a>`);
+});
+const startedAt=new Date().toISOString();
+server.listen(4317,'127.0.0.1',()=>console.log(JSON.stringify({event:'ready',url:'http://127.0.0.1:4317/',pid:process.pid,startedAt})));
+for(const signal of ['SIGINT','SIGTERM']as const)process.on(signal,()=>server.close(()=>process.exit(0)));