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

package/package.json

@@ -1,6 +1,134 @@
 {
   "name": "@kelloggt/dsh-program-agents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Supervised TypeScript/JavaScript programs for DeepSeek Harness",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/tkellogg/dsh-program-agents#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tkellogg/dsh-program-agents.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tkellogg/dsh-program-agents/issues"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "program-agents"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "main": "./dist/host/index.js",
+  "types": "./dist/host/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/host/index.d.ts",
+      "default": "./dist/host/index.js"
+    },
+    "./endpoints": {
+      "types": "./dist/endpoints.d.ts",
+      "default": "./dist/endpoints.js"
+    },
+    "./app": {
+      "types": "./dist/app/index.d.ts",
+      "default": "./dist/app/index.js"
+    },
+    "./monitoring": {
+      "types": "./dist/monitoring/index.d.ts",
+      "default": "./dist/monitoring/index.js"
+    },
+    "./supervision": {
+      "types": "./dist/supervision.d.ts",
+      "default": "./dist/supervision.js"
+    },
+    "./sdk": {
+      "types": "./dist/sdk/index.d.ts",
+      "default": "./dist/sdk/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    },
+    "./client": "./dist/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "cordis.patch.yml",
+    "docs/installation.md",
+    "docs/log-format.md",
+    "docs/publishing.md",
+    "docs/supervision.md",
+    "skills",
+    "schemas"
+  ],
+  "dependencies": {
+    "@deepseek-ai/schemastery": "3.18.5",
+    "@modelcontextprotocol/core": "2.2.0",
+    "ajv": "^8.20.0",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2",
+    "@types/node": "^22.18.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "esbuild": "^0.25.0",
+    "hono": "^4.13.13",
+    "linkedom": "^0.18.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-renderer"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/build-client.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck:references": "tsc --noEmit -p tsconfig.references.json",
+    "test": "tsx --test tests/*.test.ts",
+    "check": "pnpm build && pnpm typecheck:references && pnpm test",
+    "example": "tsx examples/standalone-supervisor.ts",
+    "release:pack": "node scripts/release.mjs pack",
+    "release:inspect": "node scripts/release.mjs inspect",
+    "release:login": "pnpm login",
+    "release:publish:dry-run": "node scripts/release.mjs publish --dry-run --no-git-checks",
+    "release:publish": "node scripts/release.mjs publish"
+  }
 }

package/schemas/dsh.http.request.v1.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dsh.dev/schemas/dsh.http.request.v1.schema.json",
+  "title": "dsh.http.request.v1 required data payload",
+  "type": "object",
+  "required": ["method", "path", "status"],
+  "properties": {
+    "method": {"type": "string", "minLength": 1, "maxLength": 32},
+    "path": {"type": "string"},
+    "status": {"type": "integer", "minimum": 100, "maximum": 599},
+    "duration_ms": {"type": "number", "minimum": 0}
+  },
+  "additionalProperties": true
+}

package/schemas/dsh.program.error-batch.v1.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dsh.dev/schemas/dsh.program.error-batch.v1.schema.json",
+  "title": "dsh.program.error-batch.v1 required data payload",
+  "type": "object", "required": ["key", "groups", "count", "range", "dropped"], "additionalProperties": true,
+  "properties": {
+    "key": {"type": "string"}, "count": {"type": "integer", "minimum": 1}, "dropped": {"type": "integer", "minimum": 0},
+    "range": {"type": "object", "required": ["first", "last"], "properties": {"first": {"type": "string"}, "last": {"type": "string"}}, "additionalProperties": false},
+    "groups": {
+      "type": "array", "minItems": 1, "maxItems": 20,
+      "items": {
+        "type": "object", "required": ["fingerprint", "count", "sample", "range"], "additionalProperties": true,
+        "properties": {
+          "fingerprint": {"type": "string"}, "count": {"type": "integer", "minimum": 1}, "sample": {"type": "object", "description": "Redacted representative standard record; large payloads/stacks/extensions may be omitted."},
+          "range": {"type": "object", "required": ["first", "last"], "properties": {"first": {"type": "string"}, "last": {"type": "string"}}, "additionalProperties": false},
+          "source": {
+            "type": "object", "additionalProperties": false,
+            "properties": {"path": {"type": "string"}, "offset": {"type": "integer", "minimum": 0}, "run": {"oneOf": [{"type": "string"}, {"type": "object", "required": ["id", "generation"], "properties": {"id": {"type": "string"}, "generation": {"type": "integer", "minimum": 0}}, "additionalProperties": false}]}}
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/dsh.program.error.v1.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dsh.dev/schemas/dsh.program.error.v1.schema.json",
+  "title": "dsh.program.error.v1 optional data payload",
+  "description": "Payload schema only, not the full record. data may be omitted. Additional application/error metadata is allowed; errors under any other log_type are still monitored by ERROR level.",
+  "type": "object",
+  "additionalProperties": true
+}

package/schemas/standard-log-record.v1.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dsh.dev/schemas/standard-log-record.v1.schema.json",
+  "title": "DSH extensible standard JSONL record v1",
+  "description": "One UTF-8 JSON object per line; at most 65536 bytes, JSON depth at most 32. Runtime rejects non-finite/lossy JSON. Unknown versioned log types are accepted by this base contract.",
+  "type": "object",
+  "required": ["timestamp", "level", "log_type", "message"],
+  "properties": {
+    "timestamp": {"type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$"},
+    "level": {"enum": ["DEBUG", "INFO", "WARNING", "ERROR"]},
+    "log_type": {"type": "string", "maxLength": 256, "pattern": "^[a-z][a-z0-9_-]*(\\.[a-z][a-z0-9_-]*)+\\.v[1-9][0-9]*$"},
+    "message": {"type": "string"},
+    "operation_id": {"type": "string"},
+    "event_id": {"type": "string"},
+    "fatal": {"type": "boolean", "description": "Advisory fatal/unhandled metadata; ERROR level determines monitoring independently."},
+    "error": {
+      "type": "object", "required": ["name", "message"], "additionalProperties": true,
+      "properties": {
+        "name": {"type": "string"}, "message": {"type": "string"}, "stack": {"type": "string"},
+        "code": {"type": ["string", "number"]}, "fingerprint": {"type": "string"}
+      }
+    },
+    "data": {}
+  },
+  "additionalProperties": true
+}

package/skills/program-agents/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: program-agents
+description: Program agents are regular scripts & apps that are monitored & maintained by agents (you). Use this skill to learn when & how to use them or manage them. Good uses include polling for jobs, files, web services, builing dashboards, giving more visibility, gathering user input in novel new ways, etc.
+---
+
+# Program agents
+
+A program agent is ordinary trusted code supervised by the current DSH parent Agent. It is **not an autonomous LLM loop, RLM, REPL or security sandbox**. Prefer one program per cohesive service/watch task. Launch through the program tools, not a detached bash job: that gives this exact parent ownership, process-group stop/restart, logs and the pinned composer strip. The user can Start/Stop/Restart it without seeing internal IPC.
+
+A program agent can have a web UI, but do not have to. It is recommended to build a UI so that the user can participate. They
+can also send and recieve messages to and from regular DSH agents, and the parent DSH agent can edit & restart the program agent
+as needed.
+
+Uses for program agents (these are suggestions, don't limit yourself to them, build on top of them):
+
+1. **Polling** — have a program agent frequently poll a web resource (or open a websocket/SSE), and when the resource is ready, forward a message to the parent DSH agent. e.g. Connect to Slack, poll for Github issue updates, alert on file changes, poll for job completion, etc.
+2. **Dashboards** — Humans get easily overloaded by text, and it often helps to UI that's dynamically changing. This is a great way to communicate status to the user, or explain data that's otherwise difficult to understand. It's important to keep dashboards up-to-date. Dynamically changing data is usually appreciated, but confirm this with the user.
+3. **Apps** — Agents are great for highly complex use cases. Sometimes the user just needs a very simple and repeatable use case. For these, build an app with a regular backend; maybe a CRUD app. Wire in messaging to agents to handle errors or handle bulk user input.
+4. **Optimization loops** — setup a loop to optimize code or business processes. Setup a subagent to the program agent to handle making changes, and create a dashboard to show progress to the user and let the user participate more in optimization.
+
+If you're deciding what to build, please read [ui-patterns](ui-patterns.md).
+
+Program agents are fundamentally a way to use agents in a more high leverage way. Focus LLMs on the control plane instead of the
+data plane. Another way to think about it is, "personal SaaS where the agent is the Ops team & development team combined".
+
+## Error handling & Logging
+Fail fast on unexpected, unrecoverable failures; do not deliberately leave expected validation or operational errors unhandled. Initialize `connectProgram({logger:{logsPath:'./logs',stdout:true,private:true}})` and explicitly register `installGlobalErrorHandlers(dsh.logger)`. That handler writes a standard fatal ERROR, attempts a bounded flush, then exits nonzero—it does not swallow the failure or keep a corrupted process alive. The host, not each application error handler, durably buffers/deduplicates standard ERROR records and routes them to the configured supervisor. Do not also send the same error manually.
+
+Use DEBUG for detailed diagnostics/metrics, INFO for normal milestones (roughly one completion record per web request), WARNING for recoverable/degraded conditions, and ERROR for failed operations that warrant supervisor attention. ERROR does **not** necessarily mean the process must exit; `fatal:true` denotes fatal errors. Use the structured logger rather than ad-hoc text. [Log schemas and conventions](log-format.md) define the wire format.
+
+You (the agent) should know:
+1. About any unhandled error, so you can learn about new edge cases and handle them. Don't assume you know the edge cases, learn about them from actual usage.
+2. What the user was doing. Capture enough in the logs to figure out what the user was doing when things broke. Also carefully track interactions with external services. The usual — anything that can be unpredictable should be tracked carefully. Keep metrics, counts, latencies, etc. Generally keep these as DEBUG messages.
+3. What external services were doing. Keep metrics, counts, latencies, etc. Generally keep these as DEBUG messages.
+
+Use an [operation ID](log-format.md) to correlate events across web requests, tool calls and messages; retain the same ID as `correlationId` for related Agent requests. Configure the logger's single active file as `./logs/app-log.jsonl` (or a registered logsPath); it rotates on size/UTC-day boundaries with bounded retention. JSONL records must have a stable versioned `log_type`, timestamp, level and message. Event IDs deduplicate stdout/file observations. Never log credentials, raw Cookie/Authorization headers, request bodies or sensitive personal data by default; key redaction does not make arbitrary free text or stack traces safe. It's wise to setup some sort of tooling to read logs and dashboard out latencies and operational events in a form that agents can make sense of (scripts are typically fine, dashboard UIs if the user needs it). In some cases it may be appropriate to export to DuckDB.
+
+### Responding to errors
+Read [inboxes.md](inboxes.md) to understand the techical details. The simplest way to respond to errors is to log an ERROR line, but you can also use the client-side library. Also, unhandled errors should bubble up to the agent, so throwing an exception is a perfectly adequate response.
+
+When writing code, you may come across a situation which is strange and might need further diagnosis. Write code that explicitly sends a message to an agent.
+
+## Who to send a message to?
+
+1. **Parent agent** — Generally the right choice. However, it does clog the agent's inbox so don't do this if the user also needs to interact with the parent agent. Designate a child!
+2. **Designated child agent** — Use the [client library](inboxes.md) to send a message to a child agent. You'll create a name/ID for this agent such that all traffic goes to the same agent every time.
+3. **New child agent** — Alternately, instead of designating a single agent to handle all operational issues, you may consider launching off multiple agents to handle incidents. This may be important if latency is key, as a new agent won't ever have to wait for another message to finish.
+
+
+## Integration references
+
+- Read [endpoints.md](endpoints.md) before publishing app URLs: persist endpoint/path recipes, bind and report an OS-assigned port through `connectProgram().endpoints.listen`, and let the harness/browser supply reachable hostnames. Includes restart collisions, remote/Tailscale access, bind policy and security caveats.
+- Read [inboxes.md](inboxes.md) for the app-side library: managed `inbox.receive(options, async handler)` automatically renews and settles claims; `agents.ask` validates one accepted typed response; `agents.send` and `ask` can create named/fresh child Agents; `tools.listTools/callTool` mirror the official MCP client tool shape. Tool access is limited to existing DSH tools registered through the normal DSH tool API and connected MCP tools. ERROR logs automatically reach the configured supervisor; semantic app workflows can contact it for intelligence as well.
+- Read [models.md](models.md) for named model slots with purpose descriptions, user-editable Models widgets in the DSH composer strip, durable overrides and explicit native model calls. Slot preferences never change the parent/global model.
+- Read [chat-sidebar.md](chat-sidebar.md) for native DSH/subagent conversations with history/event streaming and a copyable React sidebar + Hono backend. Append bounded, allowlisted page context on each user turn; never rewrite stable system/history prefixes to inject UI state.
+- Read [log-format.md](log-format.md) for the versioned JSONL standard, extensible `log_type` schemas, structured logger, buffering, redaction and rotation.
+- `program_register` accepts optional `supervision` (restart policy/budget/backoff, startAtStartup, supervisor route, error buffering) and explicit `access` grants. Defaults do not auto-restart/start. Startup runs only for existing, unarchived parent Sessions.
+
+## Recommended stack
+
+- **TypeScript**, Node22.18+ (Node26 on this Mac), ESM; pnpm with a committed lockfile.
+- **Hono + @hono/node-server** for a small typed HTTP app/API; **Zod** for external data validation. Use harness-supplied listener settings and prefer OS-assigned dynamic ports with [endpoint recipes](endpoints.md), not a hardcoded hostname/port. Bind local apps to `127.0.0.1` by default; remote exposure requires deliberate harness configuration. Never silently kill another service holding a fixed port.
+- **Vite + React** for a genuinely interactive UI; use plain server-rendered HTML for simple dashboards. Keep the frontend/API on a consistent origin or explicitly document dev proxying. Publish a UI URL the user can actually open.
+- **SQLite** for transactional application state (Node's `node:sqlite` when appropriate, migrations, WAL, parameterized queries). It is the default for mutable single-user apps/queues/idempotency keys. Do not use a JSON file as a concurrent database.
+- **DuckDB** for analytics, columnar/CSV/Parquet exploration and batch reporting, not the default hot transactional service database. Prefer the supported Node `@duckdb/node-api` binding if needed. Avoid multiple uncoordinated writers and do not introduce PostgreSQL/Docker for a tiny local app without a reason.
+- **tsx watch** for the Node/TypeScript server (`pnpm exec tsx watch src/server.ts`), Vite's dev server for frontend reload. Node `--watch` is another good option for erasable TS or built JS. Keep the watcher as the supervised foreground process so all descendants stay in its process group. Ignore generated DB/log paths to avoid reload loops. If the entire watcher exits, it is restarted only when the program's explicit supervision policy opts in; restart budget/backoff applies.
+
+Do not change this Mac's model budgets, subscription credentials, running DSH server or unrelated workstation configuration to run an app.
+
+## Shared launch description
+
+Register a program with:
+
+- `name`: short user-facing app/task name, not a UUID.
+- `description`: one sentence about what it does.
+- `command`: **argv array**, executable then arguments; no implicit shell. Use an absolute executable path if PATH ambiguity matters. Use `['pnpm','run','dev']`, not a shell string with `cd`, `&`, redirects or interpolated user data. A program is trusted code; review before launch.
+- `cwd`: app's working directory (relative paths resolve from the current parent working directory).
+- `endpoints`: named listeners, usually `{"web":{"port":"dynamic"}}`. The app must consume harness settings and report its actual bound port; `connectProgram().endpoints.listen('web', server)` does both. Do not persist a previous run's evaluated port or browser hostname.
+- `urls`: prefer `{id,title,type:'ui'|'api'|'docs',endpoint:'web',path:'/api',docs?}` for app-owned listeners. An endpoint/path recipe is mutually exclusive with literal `url`; absolute HTTP(S) URLs and informational documentation paths remain supported. Usually0–1 UI URL. `ui` is for the user, `api` for agents/tools, `docs` for discovering usage. **An API should also have documentation:** a docs URL, a docs resource on the same endpoint, or an absolute local README/OpenAPI path. Filesystem docs are informational paths for file tools, not file:// web links. Never put auth tokens in URLs. See [endpoints.md](endpoints.md).
+- `logsPath`: optional existing log file or directory owned by the app. If omitted the supervisor captures bounded stdout/stderr to an actual private file and returns its path in the run. Use file tools or `tail` to inspect; do not paste log floods into chat.
+
+Example tool argument:
+
+```json
+{
+  "name": "Inventory",
+  "description": "Local inventory editor and stock-level API.",
+  "command": ["pnpm", "run", "dev"],
+  "cwd": "/absolute/path/inventory",
+  "endpoints": {"web":{"port":"dynamic"}},
+  "urls": [
+    {"id":"app","title":"Open inventory","type":"ui","endpoint":"web","path":"/"},
+    {"id":"api","title":"Inventory API","type":"api","endpoint":"web","path":"/api","docs":"/absolute/path/inventory/docs/api.md"},
+    {"id":"docs","title":"API docs","type":"docs","url":"/absolute/path/inventory/docs/api.md"}
+  ]
+}
+```
+
+For this example, bind the app's server with `await connectProgram().endpoints.listen('web', server)`; registration metadata alone cannot change a hardcoded listener. The harness supplies bind interface/protocol and defaults public links to the viewing browser's hostname. Dynamic ports are selected afresh at bind time; remote/Tailscale access still needs reachable interfaces and ACLs. Do not silently widen exposure or assume the DSH page's HTTPS gives the app TLS. Read [endpoints.md](endpoints.md) for the full contract.
+
+Call `program_register`; its returned `program` is the opaque launch key. Then `program_start({program})` or let the user press Start. Registering does not execute code. Re-register the same name to update the description/launch command; restart when the command itself changes. Ordinary source edits should be picked up by the watcher; don't keep asking the user to restart.
+
+Launch descriptions survive DSH/plugin restart on this machine; running execution state does not. They are scoped to the parent Session. The UI's Start button dispatches the exact live parent's public `program_start` tool under its policy, not an unrelated user shell. Current parent must be live; never manufacture a different parent Agent just to launch a child.
+
+## Supervise with minimal user overhead
+
+1. Create the app, install only needed dependencies, add a reproducible `dev` command and brief README/API docs.
+2. Register metadata and a watch/reload command. Run migrations/backups explicitly before side-effectful changes.
+3. Start it. `program_start` returns on process connection/spawn, **not application readiness**. Endpoint links stay unavailable until the app binds and reports its actual port. Verify UI/API health using the current binding and inspect logs; don't claim a working app from a spawned PID alone. Browser-facing hostnames may differ from server-local health addresses—see [endpoints.md](endpoints.md).
+4. `program_list` returns descriptions and current runs, typed links, generation and log paths. Stop/restart controls require exact id+generation; stale controls must not mutate newer runs.
+5. Use UI URL for the user; use API URL+docs for automation. Prefer typed structured API calls to scraping a dashboard. Never automatically fetch arbitrary linked resources under DSH's origin.
+6. If the SDK program notifies its parent, handle it as background context and continue work. Do not ask the user to relay messages, open a message pane or acknowledge IPC. Notify the user only for a genuine decision, permission, completion or actionable problem.
+7. Before retrying external writes after crash/cancel, check external state. Effects may have unknown outcomes; implement SQLite transactions/idempotency keys or equivalent application deduplication. No exactly-once/replay promise.
+8. Stop disposable smoke tests. Leave a useful app running when that is the user's intent and give its URL without unnecessary diagnostics.
+
+## Optional SDK
+
+Ordinary foreground commands need no special entrypoint. Use `@kelloggt/dsh-program-agents/app` for supervisor messaging, MCP-shaped tool calls, typed Agent requests and managed durable inboxes in watched apps; see inboxes.md. For explicit model/tool calls, parent escalation, dynamic URLs/status or legacy in-process inbox control, a configured trusted TypeScript entry can use `@kelloggt/dsh-program-agents/sdk` and export `default async function main(ctx)`. Named capabilities and exact tool routes require grants; registering an arbitrary command does not grant tools. Model calls use existing native adapter routes/credentials and optional user-controlled slots; creating a conversational child with a selected model also obeys native subagent model-selection policy. API keys remain in the broker. The process is still trusted OS-user code, not isolated from files/network.
+
+`ctx.parent.send(json)` automatically routes to the configured supervisor (parent by default; bounded/rate-limited). It is for exceptional agent coordination, not a user messaging interface. Passive status/log changes never wake the LLM. `ctx.resources.publish({id,title,type,url,docs?})` updates typed resources; stopped generations lose live links. Docs files stay informational. Use a watch child/SDK lifecycle deliberately: killing an SDK entry on each edit can break its IPC; ordinary command watch mode is the simplest app workflow.
+
+## Limits and operations
+
+POSIX/macOS/Linux only. The supervisor controls a process group and will refuse overlapping restart if old closure cannot be proven. It is not an OS sandbox; don't run untrusted code. Capture logs are bounded/rolling, not an audit archive; use your own retention for production data. Metadata SSE carries only compact state/links, not tokens/chat/log floods. The folded composer strip stays with the parent and updates automatically; there is no Refresh or user message form.

package/skills/program-agents/chat-sidebar.md

@@ -0,0 +1,23 @@
+# App-owned assistant sidebar (copyable reference)
+
+Use this when a supervised web app needs a small chat sidebar that understands the page the human is looking at. This is an **app reference**, not a modification to the DSH composer or full conversation feed. It uses a real continuable native DSH conversation; do not implement a second model/tool loop or send ordinary chat through the supervisor inbox.
+
+Copy the five files in [the reference directory](references/chat-sidebar/README.md) into your app:
+
+- [AgentSidebar.tsx](references/chat-sidebar/AgentSidebar.tsx): React UI; opens only on human interaction, sends once, follows independently, reconnects with a fresh native snapshot.
+- [backend.ts](references/chat-sidebar/backend.ts): Hono routes; lazily opens one app-owned conversation and proxies only that handle.
+- [protocol.ts](references/chat-sidebar/protocol.ts): browser-pure native-frame reducer, compact snapshot reconstruction, bounded fetch-SSE reader.
+- [agent-sidebar.css](references/chat-sidebar/agent-sidebar.css): scoped, responsive styling.
+- [README.md](references/chat-sidebar/README.md): installation, typed app integration, route contract, security and lifecycle limitations.
+
+## Non-negotiable boundaries
+
+1. `connectProgram()` belongs **only on the backend**. Never ship bridge URL/token/environment to the frontend. The browser gets only same-origin, app-scoped routes, not arbitrary conversation/session IDs, tools, models, or bridge calls.
+2. Supply an explicit backend `sanitizePageState(input)` allowlist. Share selected IDs, visible filters, and small summaries—not the whole store, DOM, cookies, credentials, or hidden records. Raw requests are capped at 32 KiB; page state at 16 KiB. Plain JSON is data, not HTML or trusted instructions.
+3. Call `getPageContext()` only when the human sends a new message. Context is appended to that new user turn in the native SDK's explicit untrusted-data wrapper. Never rewrite the system prompt or previous history on page changes; never send page state from render/effect/polling loops.
+4. Keep the persona and model stable at conversation creation. Provider prompt caching is best-effort, not a guarantee; changing a route invalidates caches in the ordinary way. A model slot is not a selector on the parent composer. Existing conversations keep their creation-time route: a new route/persona requires a deliberately different conversation name.
+5. Follow `handle.events({ signal, maxMessages: 20 })` independently of send/ask. The native stream starts with a replacement snapshot; native assistant chunks are ephemeral and settle to durable events. Do not invent token event names, append duplicate baseline rows, or render reasoning by default.
+6. An accepted receipt means native admission, not successful tool execution. A dropped send response has an **unknown outcome**. Preserve its request ID, reconnect, and inspect history before deciding whether to resend. Native request IDs are correlation, not an exactly-once or automatic-deduplication promise.
+7. Enforce exact app Origin on writes, exact configured host, no wildcard CORS, and real app authentication where needed. Same-origin browser GETs normally omit Origin; the reference permits only the documented GET-only `Sec-Fetch-Site: same-origin` plus non-simple custom-header exception. Localhost cookies are not port-isolated; see the security section in the reference README.
+
+Read [the complete integration instructions](references/chat-sidebar/README.md) before copying or publishing routes. This reference does not install dependencies, launch a server, change a running DSH instance, or provide a production authentication system.

package/skills/program-agents/endpoints.md

@@ -0,0 +1,92 @@
+# Runtime endpoint recipes and direct remote access
+
+A URL has two lifetimes: a **persisted recipe** and a **current listener address**. Never save an evaluated dynamic port or last browser hostname as the launch definition. No stored JavaScript, interpolation, eval, or shell expansion is involved.
+
+## Registration
+
+```json
+{
+  "name":"Inventory",
+  "description":"Local inventory app and API",
+  "command":["pnpm","run","dev"],
+  "cwd":"/absolute/path/inventory",
+  "endpoints":{"web":{"port":"dynamic"}},
+  "urls":[
+    {"id":"ui","title":"Open inventory","type":"ui","endpoint":"web","path":"/"},
+    {"id":"api","title":"Inventory API","type":"api","endpoint":"web","path":"/api","docs":"/absolute/path/inventory/docs/api.md"},
+    {"id":"docs","title":"App docs","type":"docs","endpoint":"web","path":"/docs"}
+  ]
+}
+```
+
+`endpoints` is a map of at most16 named listeners. `port` is `"dynamic"` or an explicit integer1–65535. Recipe URLs use `endpoint` and optional `path` (default `/`), mutually exclusive with legacy `url`. Multiple UI/API/docs paths may share a listener. Paths include query/hash if useful but cannot change authority or carry raw controls/backslashes. Filesystem documentation remains informational; no `file://` links. Legacy absolute HTTP(S) URLs continue unchanged, including deliberately external links: the harness never globally rewrites `127.0.0.1` inside arbitrary strings.
+
+Registration persists the recipe only. A fresh process generation starts with requested port0 for dynamic listeners, no bound port and unavailable links. A listener's actual port becomes available only after the app binds and reports it. Stop/crash/restart clears binding/link availability. The strip receives pushed metadata and resolves links again; it never needs a manual Refresh.
+
+## Bind with the app helper
+
+```ts
+import {createServer} from 'node:http';
+import {connectProgram} from '@kelloggt/dsh-program-agents/app';
+
+const app=connectProgram();
+const server=createServer((req,res)=>res.end('Hello'));
+const listener=await app.endpoints.listen('web',server);
+console.log('Local health address:', listener.localUrl);
+// On orderly shutdown:
+await listener.close();
+```
+
+The helper asks the authenticated host for this generation's binding policy, calls `server.listen({host,port})`, waits for listening, reads `server.address().port`, then publishes it. For dynamic ports the OS selects and holds port0 atomically—no probe/free/rebind race. It does not guess a free port, reserve it briefly, or promise the previous port survives a restart. If the old port is occupied, the next dynamic launch uses an available one. Fixed-port collisions fail normally and never advertise an unbound endpoint. There is no automatic retry of app side effects.
+
+`listen` takes a Node net/http-compatible Server, so Hono's Node handler can use `createServer(getRequestListener(app.fetch))`; use the same pattern with a framework's server adapter. For separate frontend/backend listeners, register distinct endpoint names. Prefer a single-origin app when possible so asset URLs and relative API requests follow the browser's actual host/port. Configure Vite/framework host/origin settings deliberately; DSH does not rewrite arbitrary HTML, asset paths or redirects.
+
+For framework-owned listeners:
+
+```ts
+const policy=(await app.endpoints.list()).find(x=>x.id==='web');
+if(!policy) throw new Error('web endpoint is not registered');
+// Bind using policy.bindHost and policy.requestedPort (0 for dynamic), then:
+await app.endpoints.publish('web',{port:actualBoundPort});
+// On close (port condition prevents an old worker clearing a replacement):
+await app.endpoints.unpublish('web',{port:actualBoundPort});
+```
+
+Per-run policy is also in `DSH_PROGRAM_ENDPOINTS_JSON` for non-JS launchers; the app bridge has list/publish/unpublish. This environment is ephemeral harness input, not something to copy back into the saved definition. Legacy SDK entrypoints can use `/app` alongside `/sdk`; ordinary watched commands need no special entrypoint. A reload worker reads `requestedPort`, not a previously reported `port`. Worker replacement can report a fresh port in the same generation. Publication is not a health-check assertion beyond the helper's successful local bind; use actual health endpoints.
+
+## Harness host policy
+
+Plugin config, not registration or a request Host header, controls exposure:
+
+```yaml
+networking:
+  bindHost: 127.0.0.1
+  publicHost: browser
+  protocol: http
+```
+
+Defaults are local-only bind, browser-host links, HTTP. `publicHost: browser` means render using **this browser's `location.hostname`**, excluding DSH's port. This matters with two viewers: local DSH gets `http://127.0.0.1:<app-port>/api`; a Tailscale viewer gets `http://devbox.tailnet.ts.net:<app-port>/api`. Browser hostname is evaluated when constructing each link, not persisted, and never controls where a server listens. An explicit public DNS/IP hostname overrides the browser default. IPv6 is supported/bracketed appropriately. Agent/server health checks use a server-local address, not a guessed remote-browser authority; returned binding metadata exposes bindHost+actual port separately from the public recipe.
+
+### Tailscale direct-port mode
+
+Configure `bindHost` to the server's **Tailscale interface address** to expose only that interface, or another deliberately reachable bind address. The user/harness owns that setting. Don't silently change a local app to `0.0.0.0`: that can expose it on Wi-Fi/LAN too. A Tailscale-only bind may not accept `127.0.0.1`; if DSH is viewed locally through loopback, configure an explicit Tailscale `publicHost` or view DSH through its Tailscale name. `publicHost: browser` is correct only when the browser's hostname reaches the app's configured interface.
+
+Tailscale ACL/firewall policy must permit the app's selected ports. Dynamic ports aren't automatically tunneled or opened. The current implementation uses **own ports**, as selected by the user—not a DSH same-origin reverse proxy. Tailscale provides the private network but is not per-app authorization: add app auth for sensitive services or other authorized tailnet users.
+
+`protocol` describes the app listener, not the DSH page. Opening DSH over HTTPS does not magically give a plain Node HTTP listener TLS; default links remain HTTP. Set HTTPS only when the app itself serves HTTPS with valid certificates at that hostname/port. Tailscale transport encryption is separate from browser HTTPS. This direct mode does not implement Tailscale Serve mappings, HTTPS termination, SSH forwarding of arbitrary dynamic ports, or one-port proxy support. A browser following a link navigates in a separate tab; DSH never fetches/embeds app content with its credentials.
+
+## Lifecycle and security
+
+- Different ports are different browser origins, **but cookies are not port-scoped**. A browser may send matching hostname/path cookies to an app on another port. HttpOnly prevents JavaScript reads, not a receiving HTTP server from seeing Cookie headers. These are trusted OS-user programs, not a hostile-code isolation boundary. Do not log/forward Cookie or Authorization headers; use a separate app hostname and appropriately scoped DSH cookies if cookie isolation is required. No reverse proxy is added here.
+- Host metadata has structured `address:{endpoint,host,protocol,port,path}` only after a report; recipe `url` is empty, never an old port string. The browser validates shape/host/path again. Unbound, stale, stopped, pending-action, malformed links are disabled.
+- Bridge credential selects exact live owner/run/generation. A stale generation cannot report or unpublish a newer listener. Program input cannot set bindHost/publicHost/protocol through report methods. Trust boundary remains trusted OS-user code, not a network sandbox; custom code could still ignore instructions and bind differently.
+- Configured recipe resource IDs cannot be overwritten via legacy `resources.publish`; report/unpublish the endpoint instead. Arbitrary external static resources remain supported.
+- Runtime does not probe/fetch advertised URLs or auto-kill another service holding a fixed port. Do not adopt another process's listener after EADDRINUSE.
+- OS-assigned ports solve collision/restart allocation for integrated apps. A generic black-box command hardcoded to a port must be adapted to consume harness configuration and report readiness; metadata alone cannot change its listening socket.
+- No URLs, browser hostnames or evaluated port bindings are saved back to launch recipes on exit. App databases and idempotency remain separate from endpoint lifecycle.
+
+## Example and validation
+
+`examples/dynamic-server.ts` (built `dist/examples/dynamic-server.js`) is an ordinary command using the helper. Register endpoint web dynamic and UI `/`, API `/api/status`, docs `/docs` if actually implemented (the example only serves UI and API).
+
+Tests cover actual bind0 and publication, restart with previous port occupied by another process, no advertising before bind, fixed-port collision, bridge failures/cancellation/close cleanup, stale generations, per-browser local/Tailscale/IPv6 hostname resolution, host injection attempts, backward-compatible static resources and persisted recipe reload. Network reachability on a real remote Tailscale client requires that actual environment; local tests do not claim remote ACL/TLS verification.

package/skills/program-agents/inboxes.md

@@ -0,0 +1,120 @@
+# Managed program integration: inboxes, Agents and MCP-shaped tools
+
+Use `@kelloggt/dsh-program-agents/app` in ordinary watched programs. The library connects through private per-run/generation credentials supplied by DSH; no special entrypoint or browser cookie/provider credentials. Do not print or forward `DSH_PROGRAM_*` credentials. The composer stays compact, with no extra human message widget.
+
+```ts
+import {connectProgram,installGlobalErrorHandlers,responseType} from '@kelloggt/dsh-program-agents/app';
+const dsh=connectProgram({logger:{logsPath:'./logs',stdout:true,private:true}});
+installGlobalErrorHandlers(dsh.logger);
+```
+
+## Managed inbox: receipt before handler, settlement after await
+
+Prefer this scoped async-handler form—not manual ACK/NACK plumbing:
+
+```ts
+const result=await dsh.inbox.receive({
+  waitMs:25_000,
+  leaseMs:60_000,
+  processingTimeoutMs:120_000,
+  signal:shutdown.signal,
+}, async(message,{signal})=>{
+  // Already claimed durably before invocation. Message is readonly and has no token.
+  // Validate app payload; use message.id as a transactional idempotency key.
+  await applyIdempotently(message.id,message.body,{signal});
+  if(bad) throw new Error('very bad'); // managed NACK after callback settles
+  return 'very good';                 // managed ACK before receive resolves
+});
+```
+
+An async callback is modern structured lifetime management: DSH awaits it in a try/finally-style scope. Return/fulfilled Promise means ACK, throw/rejected Promise means NACK. Lease heartbeat renews while processing; the callback sees a cooperative cancellation `signal`. No handler is invoked when no message arrives; receive returns null. Callback return is a local result, not an automatic reply to another Agent. An accepted Agent request uses the separate reply protocol below.
+
+Receipt states remain **accepted** (durably enqueued), **claimed** (leased before handler invocation), **acked** (handler succeeded and ACK was confirmed). Lease tokens are hidden in managed callbacks. Prefer `receive(options,handler)` or `receive(handler)`. Deprecated `receive(options)` remains manual; explicit low-level `claim`, `renew`, `ack`, `nack`, `receipt` exist only for special transport integration. Do not mix manual settlement into a managed callback.
+
+### Honest failure guarantees
+
+- The helper never automatically reruns your callback, retries ACKs, or ACKs an interrupted/lease-lost callback.
+- Lost ACK response may mean it already committed: `SettlementUnknownError` includes `messageId` and `outcome:'unknown'`. Inspect retained receipt/application idempotency state; do not NACK/repeat the effect blindly.
+- Exceptions get one fenced NACK attempt. Failed NACK leaves the lease to expire; it does not become proof of rollback.
+- Cancellation/heartbeat failure aborts the callback signal. Noncooperative JS cannot be forcibly stopped in-process. The API retains its callback slot until it actually settles, never ACKs it late, renews only within its bounded processing deadline, then permits lease expiry. Redelivery and overlapping external effects remain possible after expiry. Use transactions/idempotency and honor signal.
+- Crash/kill cannot execute finally. SQLite leases eventually expire or host generation revocation releases them. This is durable **at-least-once delivery**, not exactly-once execution.
+- Pending callbacks, lease duration (max5min per renewal), processing duration (default2min/max1h), queue/retained receipts/bytes are bounded. A handler that blocks the JS thread also blocks heartbeats; choose suitable workers and bound work.
+
+The Agent writes new work via `program_inbox_send({parent_id?,program,correlation_id?,body})`. Owning parent may omit parent_id; direct child supplies the parent's ID. Only that scope is admitted. Inbox persistence is message transport, not restoration of arbitrary app execution memory.
+
+## Send or ask an Agent, with implicit creation
+
+```ts
+// Existing explicit identity: never silently replaced when missing.
+await dsh.agents.send('child-session-id',{type:'work-ready'});
+
+// Named get-or-create, scoped to the owning parent's continuable children.
+await dsh.agents.send({name:'Triage',instructions:'Review support issues.'}, {issue});
+const summary=await dsh.agents.ask({name:'Triage'}, {issue}); // Promise<string>
+
+// Explicitly fresh child per call. Normal parent's delegation policy/model applies.
+const result=await dsh.agents.ask({create:{name:'Reviewer',instructions:'Assess the supplied change.'}}, {patch});
+```
+
+`agents.list/get` discover only the parent and its actual direct-child catalog. Named duplicate ambiguity is an error; use exact ID. Both send and ask may create children under normal parent's public subagent tool policy, depth, model, capacity and cost limits. They do not grant root-session creation/arbitrary global messaging. Creating a child runs a bootstrap turn, then a separate work message after assignment so it cannot race the reply contract. Canceling creation can have unknown outcome—do not blindly create another child.
+
+`send` returns acceptance, not the Agent's answer. `ask` is managed request/response:
+
+```ts
+type Review={verdict:'accept'|'reject';reason:string};
+const Review=responseType<Review>({
+  type:'object',
+  properties:{verdict:{type:'string',enum:['accept','reject']},reason:{type:'string'}},
+  required:['verdict','reason'],additionalProperties:false,
+});
+const review=await dsh.agents.ask({name:'Reviewer'},{patch},Review,{
+  requestId:'review-operation-42', // stable app idempotency key, optional
+  timeoutMs:120_000,
+  signal:shutdown.signal,
+});
+```
+
+Alternatively pass `{responseSchema:jsonSchema}` as ask's options; default schema is a plain string. TS types vanish at runtime: JSON Schema is the actual response contract. Draft2020-12 validation is strict (Ajv; local refs, no remote schema fetching/coercion/defaults/unknown formats). `responseType<T>` gives a typed identity parser but the caller is responsible for making T match the schema.
+
+Host durably records request before dispatch, binds the selected Agent before sending the work, and requires the Agent to use:
+
+```text
+program_reply({
+  parent_id:"<owning parent>", program:"<program key>",
+  request_id:"<host-generated opaque request id>",
+  body:<string or JSON matching response_schema>
+})
+```
+
+Only the assigned Agent may reply. The **first valid response is accepted atomically once**. Invalid responses reject without settling (the Agent may correct them); conflicting/late replies reject; an identical repeated response returns the existing receipt. A normal chat answer or `program_inbox_send` does not settle ask. The Agent gets exact protocol/schema/deadline in its work message. This enforces accepted response shape/cardinality, not guaranteed liveness or one model generation: timeout, cancellation, failure and unknown dispatch are explicit outcomes.
+
+`dsh.agents.request(idOrKey)` inspects durable state/answer; `.cancel(idOrKey)` cancels the response contract, not the Agent's already-started effects. `ask` polls read-only result waits; it never retries sending/delegation. Reuse a requestId only for the exact same target/body/schema/options; changed semantics reject. Host restart does not redispatch pending work. Inspect ambiguous request state before deciding to repeat. Request deadlines default2min/max1h; individual waits max30s. Requests/answers/retention have bounds: payload depth28/node9900 reserves transport framing, body/answer48KiB, schema16KiB and combined request56KiB. Rejected responses do not consume the one-response slot. Retention is bounded, so an old pruned idempotency key is not an eternal exactly-once guarantee. Only the answer and compact metadata cross the bridge on result reads; original request payload isn't echoed repeatedly.
+
+## Existing DSH and MCP tools
+
+```ts
+const {tools}=await dsh.tools.listTools();
+const result=await dsh.tools.callTool({name:'inventory.lookup',arguments:{sku:'A1'}});
+if(result.isError){ /* tool ran/reported failure; result.content describes it */ }
+else { /* result.content and optional result.structuredContent */ }
+
+const inventory=dsh.mcp.forServer('inventory');
+const {tools:mcpTools}=await inventory.listTools();
+const stock=await inventory.callTool({name:'lookup',arguments:{sku:'A1'}});
+```
+
+These names/parameter/result shapes mirror the official JS MCP Client's **tool subset**: `listTools({cursor?})` → `{tools,nextCursor?}`; `callTool({name,arguments?,_meta?})` → `{content,structuredContent?,isError?}`. Types/results use the official `@modelcontextprotocol/core` schemas. Tool failure is an `isError` result; transport/auth/policy/protocol failures throw. Underlying DSH MCP adapter may project upstream errors into its native error text. The unified list includes only granted existing DSH tools registered through the normal DSH tool API and connected MCP public names (`mcp__server__tool`, including DSH's normalized hash names). Server-scoped clients expose raw upstream names. Like the official client, a cursorless listTools call aggregates bounded pages (max64); passing an explicit cursor fetches one page and returns nextCursor.
+
+This is not a full `Client` transport implementation: no MCP initialize/stdio/http server, resources/prompts/tasks/sampling/elicitation/cache/notifications are promised. `_meta` is accepted as metadata but not forwarded as arbitrary parent tool authority. DSH native content is adapted to MCP text/structured JSON; canonical upstream MCP content is preserved when DSH retained it. Large/image results still have the bridge64KiB boundary.
+
+Apps use `tools.listTools/callTool` to access only existing DSH tools registered through the normal DSH tool API and connected MCP tools. Grant exact `access.tools` names or server-scoped `access.mcp` tools. Model inference accepts a [named configurable slot](models.md) or an explicit native route with `dsh.models.call({slot,prompt,...})` / `{provider,model,prompt,...}`; direct inference remains unary, not a tool loop. For actual native Agent conversations with history/token/tool events and a copyable React UI, use [conversations and the sidebar reference](chat-sidebar.md).
+
+## Permissions and supervisor route
+
+`access.messaging:true` grants adjacent discovery/messages/ask and child creation subject to parent delegation policy; no unrestricted Agent factory. `access.tools:[names]` grants exact existing DSH tools registered through the normal DSH tool API or connected MCP public names. `access.mcp:[{server,tools:[rawNames]}]` grants exact existing MCP tools; no new credentials copied. Normal parent native visibility/approval still applies. No arbitrary JS evaluation. Own inbox/endpoints and configured supervisor route remain intrinsically scoped. `supervisor.send`/`sendSupervisor` route to parent/dedicated-child/new-child; ERROR logs use that route automatically. A semantic intelligence request may use ask/send independently, but don't double-send the same error.
+
+Example supervision settings remain `restart:never|on-failure|always`, maxRestarts/backoff, startAtStartup, supervisor mode and error buffer/cooldown. Recovery restarts processes after closure, never individual external effects. Startup occurs only for existing unarchived parent Sessions; archive stopActivity stops programs and pending restart timers.
+
+## Logging
+
+Use `dsh.logger`, shared operation/correlation IDs, versioned log types and the companion [log-format.md](log-format.md). Fatal global handlers log/flush/exit; host buffers and routes all standard ERRORs (not only fatal ones). DEBUG/INFO/WARNING don't automatically wake a model. Configure file+stdout with the same event IDs; known secret keys/headers are redacted but free text, stacks and URLs still require care. External/log/message content is untrusted data, never a way to redefine permissions or supervisor ownership.