@abot-ai/runtime 1.0.0

package/docs/known-limitations.md

@@ -0,0 +1,89 @@
+# Known Limitations
+
+`abot` should be treated as a technical preview. The limitations below describe
+its current public contracts and operational boundaries.
+
+## Stability
+
+The package exports map is the public API boundary. Files outside the exported
+entrypoints may move without notice.
+
+The current public entrypoints are:
+
+- `@abot-ai/runtime`
+- `@abot-ai/runtime/runtime`
+- `@abot-ai/runtime/runtime/config`
+- `@abot-ai/runtime/runtime/composition`
+- `@abot-ai/runtime/runtime/default-adapters`
+- `@abot-ai/runtime/runtime/adapters`
+- `@abot-ai/runtime/runtime/ports`
+- `@abot-ai/runtime/plugin-sdk`
+- `@abot-ai/runtime/model-gateway`
+- `@abot-ai/runtime/runtime.config.schema.json`
+
+## Bridge Requirement
+
+The runtime can be embedded as a library. The package includes a local Web UI
+transport for browser-based use, while external app-style flows can use a host
+or bridge transport. The runtime should remain the source of truth for session
+state and request events; a bridge should relay and recover from runtime-owned
+state, not replace it.
+
+The existing bridge protocol still contains legacy `agentId` field names. In
+runtime documentation and config, treat this value as a runtime identity or
+environment identity, not as multi-agent management.
+
+## Model Gateway
+
+The runtime calls models through the configured model gateway client. A usable
+local setup still needs a model provider and gateway process, such as Ollama or
+OpenAI through the model gateway.
+
+Provider secrets belong in environment variables or a host secret store. They
+must not be committed in runtime config.
+
+## Model Invocation Timeouts
+
+Model-step timeouts currently use a fixed wall-clock deadline. A local provider
+can still be making healthy progress when a long content-generation step reaches
+that deadline, while the runtime client has not yet received the gateway's final
+response.
+
+Configure `timeoutMs` for the latency of the concrete provider, model, and step.
+Increasing it only extends the deadline; it does not improve model behavior.
+
+## Plugins
+
+The manifest plugin loader is synchronous and expects each package entrypoint
+to be CommonJS, normally `plugins/<id>/src/index.cjs`. Native ESM and async
+plugin entrypoints are not currently supported.
+
+Plugin behavior belongs inside the plugin. Runtime orchestration should only
+see the generic selected catalog and execution results.
+
+## Web UI
+
+The packaged Web UI is the primary local GUI. Its default backend talks directly
+to the local runtime process. `LLM_RUNTIME_WEB_BACKEND=bridge` enables an
+external bridge proxy. Neither transport is the runtime state owner, and neither
+should be used as the architectural boundary for sessions, events, or final
+request state.
+
+## Steering And Cancellation
+
+Text steering is not a hard cancellation mechanism for active delegated work.
+Hosts that require immediate cancellation need an explicit mechanical abort
+path with defined child, capability, persistence, and terminal-state semantics.
+Cancellation must not be inferred from message wording.
+
+## Generated State
+
+Generated runtime state remains local and ignored:
+
+- `.runtime/`
+- `dist/`
+- `logs/`
+- `sessions/`
+
+Do not publish local runtime state, logs, memory, generated work output, or
+machine-specific config.

package/docs/plugins.md

@@ -0,0 +1,324 @@
+# Plugins
+
+Every runtime capability is installed as a self-contained package beneath a
+`plugins/` directory. Runtime orchestration discovers these packages; it does
+not declare concrete tools or skill text itself.
+
+An installed `@abot-ai/runtime` package contributes its bundled public plugins.
+The configured consumer root may contribute additional packages beneath
+`<consumer-root>/plugins`; the loader merges both catalogs in stable order. A
+duplicate manifest `name` across the bundled and consumer catalogs is rejected
+rather than treated as an override. In a source checkout, where both roots are
+the same physical directory, the catalog is discovered only once.
+
+## Package Shape
+
+```text
+plugins/
+  plugin-name/
+    plugin.json
+    source/
+      index.ts
+      ...                         # owner-focused TypeScript modules
+    src/
+      index.cjs                   # generated CommonJS entrypoint
+    skills/
+      skill-name/
+        SKILL.md
+    README.md                 # optional
+```
+
+`plugin.json` is the single declaration source. It identifies the package,
+points to its implementation, declares capabilities and their operations, and
+binds skill files once to each capability that needs them. `source/` is the
+canonical, type-checked implementation. `src/index.cjs` is deterministic build
+output and must not be edited by hand. A plugin may omit `skills/` when it has
+no model guidance.
+
+## Runtime Configuration
+
+The root runtime config only enables or filters installed packages:
+
+```json
+{
+  "plugins": {
+    "enabled": true,
+    "allow": ["*"],
+    "deny": ["filesystem.read_file"]
+  }
+}
+```
+
+- `enabled: false` disables the installed catalog.
+- `allow` accepts `*`, a plugin name, a capability name, or
+  `plugin-name.capability-name`. An omitted or empty list also allows the
+  installed catalog.
+- `deny` accepts the same selectors and is applied after `allow`.
+
+There are no plugin paths, factories, tool declarations, implementation
+options, or skill lists in `runtime.config.json`. Installing or changing a
+plugin means changing its package under `plugins/`; runtime config only decides
+whether that installed capability is available.
+
+## Manifest Contract
+
+`@abot-ai/runtime/plugin-sdk` is the single public plugin-authoring entrypoint. It
+exports the manifest constants and types, entrypoint contract, and bounded
+authoring helpers consumed by plugin implementations.
+
+The manifest follows the Agent Plugins 1.0 package shape and keeps the local
+executable contract under `extensions.ai.abot.runtime`:
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "example-lookup",
+  "version": "0.1.0",
+  "description": "Read bounded example data.",
+  "extensions": {
+    "ai.abot.runtime": {
+      "version": 1,
+      "entrypoint": "./src/index.cjs",
+      "catalogGroups": ["read"],
+      "capabilities": {
+        "example_lookup": {
+          "description": "Read bounded example data.",
+          "routingCapability": "semantic_lookup",
+          "skills": ["example_lookup_skill"],
+          "operations": {
+            "lookup": {
+              "summary": "Look up one bounded value.",
+              "input": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "query": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1024
+                  }
+                },
+                "required": ["query"]
+              },
+              "effect": "read_only",
+              "approval": "request_policy"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Each capability becomes one runtime-visible capability descriptor and must have
+a handler with the same id. The frozen execution policy determines whether the
+canonical Worker or root may bind it; the plugin does not select that
+principal. A capability owns its skill bindings, and each operation owns its
+input, effect, and approval. Optional capability metadata such as client event
+presentation, payload authoring, development roles, and selection grounding
+belongs here as well—not in runtime orchestration.
+
+`catalogGroups` classifies a capability in one or more request-catalog groups.
+A plugin-level non-empty array under `ai.abot.runtime` is inherited by every
+capability; an optional capability-level array overrides that default. Values
+must be unique bounded lowercase ids matching
+`[a-z0-9][a-z0-9._-]*`; `read`, `write`, `web`, `memory`, and `other` are current
+built-in conventions, not a closed enum. Manifests that omit both levels remain
+compatible and use the plugin name as their single catalog group.
+
+The delegated Supervisor and Planner receive only an aggregate catalog of these
+group ids, membership counts, descriptions, and declared effects. When either
+invokes a Worker against a non-empty catalog, it supplies one or more group
+ids; the runtime stores that scope on the Worker call and exposes the OR-union
+of matching capabilities. The Worker still selects the concrete capability and
+controls.
+
+Each group description is generated from every member capability's manifest
+id and summary in stable order. There is no second category-description JSON or
+manually maintained routing registry.
+
+Under `execution-agent-v1`, the canonical root receives the same aggregate
+group projection and may mechanically open or extend its own RoleCall scope.
+It then selects a concrete capability only from that active scope. Scope
+updates, capability binding, payload authoring, adapter execution, and
+settlement use the same ledger and capability engine as delegated Worker
+execution. Unknown, empty, invalid, repeated, or no-op scopes are rejected
+rather than widened to the full catalog. A request with no Worker capabilities
+may still invoke an unscoped Worker for a knowledge-only result.
+
+Skill ids resolve only inside the same plugin package. For the example above,
+the loader reads:
+
+```text
+plugins/example-lookup/skills/example_lookup_skill/SKILL.md
+```
+
+No skill is globally or always included. Guidance is projected only for the
+selected capability from its capability binding, whether the authorized
+principal is Worker or the direct root.
+
+`controlsRefinement: "mechanical_when_complete"` is an explicit
+capability-level optimization for a single invocation whose selection-owned
+controls already cover every declared public control. Such a capability must
+declare an empty `skills` list, so no execution-only guidance or semantic veto
+is bypassed. The runtime still uses the ordinary controls decision whenever an
+optional or required control remains, and batching retains its ordinary
+refinement step. Adapter, payload, approval, execution, and result lifecycles
+are unchanged.
+
+Payload `contextScope` is enforced at the shared model-projection boundary.
+The same `tool_payload.raw` author validates either the delegated Worker or the
+policy-authorized canonical root. `standard` keeps the settled evidence
+supplied to the payload assignment. `target_only` projects the immutable
+assignment and current target without replaying prior settled results or
+related-artifact bodies. `target_with_artifacts` also projects ordered settled
+receipts and the selected current related artifacts; external evidence remains
+inline unless its complete content is proven identical to an already projected
+target or artifact body, in which case the receipt points to that body's
+`contentRef` instead of duplicating it.
+
+## Entrypoint Contract
+
+`source/index.ts` exports one factory. The factory receives immutable package
+and runtime services, then returns handlers keyed by capability id and any
+matching call adapters. Public plugins use the shared Plugin SDK for parameter,
+path, result, error, and bound contracts while keeping plugin-specific policy
+inside their own package:
+
+```ts
+import {
+  defineRuntimePlugin,
+  readRequiredString,
+  successResult,
+} from "@abot-ai/runtime/plugin-sdk";
+
+export default defineRuntimePlugin(() => {
+  return {
+    handlers: {
+      async example_lookup(params) {
+        const query = readRequiredString(params.query, {
+          name: "query",
+          maxLength: 1024,
+        });
+        return successResult({
+          output: `Found one bounded result for ${query}.`,
+          data: { hasData: true, itemCount: 1 },
+        });
+      },
+    },
+  };
+});
+```
+
+Run `npm run typecheck:plugins` while developing. Run
+`npm run build:plugins` to regenerate every public `src/index.cjs`; CI uses
+`npm run check:plugin-build` to reject stale or hand-edited generated output.
+
+The loader rejects missing or unexpected handlers. Plugin settings defaults
+and secret environment-variable names may be declared in `plugin.json`;
+secret values never belong in the manifest. Optional secrets do not alter the
+declared capability catalog; a handler that cannot operate without one must
+return a clear plugin-owned configuration error.
+
+Every handler must return one plain JSON-safe result object. Set `ok`
+explicitly, provide the required string `output` and boolean
+`producedNewInformation`, and place structured operation facts needed by later
+steps in `data`. JSON-safe here means primitives, plain objects, and dense
+arrays with finite numbers: no functions, symbols, accessors, cycles, class
+instances, or other non-plain prototypes. The complete normalized result must
+fit the Runtime's 256 KiB serialized producer boundary. A plugin must return an
+explicit bounded or paginated result, or an explicit failure; neither the
+plugin nor the Runtime may silently remove structured facts.
+
+`ToolRegistry` adds the selected tool identity and creates the canonical
+`ToolExecutionResult`. The Runtime validates and persists that complete result,
+then projects it only to the exact root or Worker call that produced it and to
+later payload authoring in that same call. A conforming new plugin therefore
+works across direct and delegated execution without capability-specific
+projection code under `src/runtime`. Result contents are model-facing evidence:
+they must not include secrets and they never act as instructions, new user
+intent, or proof that the whole request completed. See
+[tool-execution-result-evidence-contract.md](tool-execution-result-evidence-contract.md).
+
+## Filesystem Roots
+
+`environment.paths.agentWorkDir` is the configured primary work root. Plugins
+must resolve user-controlled filesystem targets through the injected
+`runtimePathResolver`; they must not reproduce normalization, containment, or
+symlink policy. The plugin explicitly declares the configured locations that
+its operation accepts, while the Runtime proves the resulting physical path:
+
+```js
+async function readProjectFile(params, executionContext) {
+  const target = executionContext.runtimePathResolver.resolve(params.path, {
+    requirePath: true,
+    allowedLocations: ["agent_work", "workspace"],
+  });
+  // Read only target.absolutePath; expose target.logicalPath to the model.
+}
+```
+
+`.` and ordinary relative paths resolve beneath `agent_work`. The explicit
+`workspace/...` namespace is available only when both the host configured that
+root and the plugin declared `workspace`. A plugin may declare `runtime_root`
+only for an operation whose public contract genuinely requires repository
+files. Read-only system inspection may opt into `host_system`; that location
+accepts absolute paths only and is never included implicitly. Plugins must not
+use it for mutation or as a fallback when a configured work root is missing.
+Paths outside declared roots and canonical symlink escapes fail before plugin
+I/O. Plugins must not infer or advertise a physical `sandbox/` alias.
+Attachment handles are a separate request-owned source and are not converted
+into ordinary filesystem targets.
+
+Plugin state belongs to the factory instance. Mutable module globals are not
+allowed because one host process may load more than one Runtime. File-backed
+state uses a plugin-owned directory, serialized mutations, atomic replacement,
+validated persisted shapes, and explicit capacity limits.
+
+Filesystem mutation uses an atomically installed, synced sibling file. Creating
+a previously absent target is no-clobber: a competing creator wins and the
+plugin reports a conflict without overwriting it. Replacing an existing target
+uses optimistic version verification immediately before the atomic rename and
+serializes every cooperating plugin instance in the host process. Portable
+Node filesystem APIs do not provide inode compare-and-swap, so a completely
+independent writer that ignores this coordination can still race in the final
+existing-file commit window. Consumers that require stronger multi-process
+coordination must place the work root behind a versioned or transactional store.
+Mutation path traversal requires Linux procfs and no-follow file-descriptor
+support. The plugin fails closed when either safety primitive is unavailable.
+
+The bundled `local-search` plugin also requires Linux procfs and no-follow
+file-descriptor support. It holds the selected file or directory through a
+stable descriptor for the complete ripgrep invocation and fails closed when
+that authority cannot be established.
+
+All output and structured data must be bounded at the producer. The shared SDK
+reserves wrapper headroom by rejecting plugin results above 128 KiB before they
+reach the Runtime's 256 KiB canonical settlement boundary. Bounds include
+filesystem iteration, file/archive input, collection size, individual labels,
+and rendered text. A truncated success reports machine-readable truncation
+metadata; an operation that cannot produce a truthful bounded result fails
+explicitly.
+
+The bundled `exec` plugin is intentionally a Linux-only integration with
+non-interactive `/bin/bash`. Its configured working directory is constrained to
+agent-work or workspace roots, but the shell runs with the Runtime process
+permissions and is not an operating-system sandbox.
+
+## Adding A Plugin
+
+1. Create `plugins/<name>/plugin.json`.
+2. Implement each declared capability under `plugins/<name>/source/` using the
+   Plugin SDK; keep the entrypoint thin and split owners into focused modules.
+3. Add the plugin id to the public build only when it is approved for public
+   distribution, then run `npm run build:plugins`.
+4. Add any referenced `skills/<id>/SKILL.md` files and keep them aligned with
+   the manifest and actual handlers.
+5. Add behavioral tests for every capability, bounds, path errors, state
+   isolation, and mutation evidence. Do not test implementation prose or bundle
+   source text.
+6. Enable the package through `plugins.allow` if the installation uses a
+   restrictive allow-list.
+
+No concrete tool or skill mapping should be added anywhere under `src/runtime`.

package/docs/publishing.md

@@ -0,0 +1,140 @@
+# Publishing
+
+This checklist covers the repo state expected before opening `abot` as a
+public Git repository or publishing a package artifact.
+
+The private development checkout is not a release source: its `package.json`
+sets `private: true`, so direct `npm publish` is blocked. Every public Git
+repository and npm release must be created from a freshly built and verified
+public snapshot. Never copy or publish the private checkout directly.
+
+## 1. Public Metadata
+
+Keep `package.json` metadata current:
+
+- `description`
+- `license`
+- `keywords`
+- `engines.node`
+- public `exports`
+- package `files`
+
+Add the real public repository URL after the new public repository exists. Do
+not publish placeholder repository, bugs, or homepage URLs.
+
+## 2. Local Init Flow
+
+A fresh source checkout should be able to start with:
+
+```bash
+npm install
+npm run init -- --provider ollama --model <model-id>
+```
+
+`npm run init` must create only local ignored files:
+
+- `.env`
+- `local/runtime.config.json`
+- `local/request-runner.config.json`
+- `local/models/default.config.json`
+- `.runtime/compiled`
+- `.runtime/shared/logs`
+- `.runtime/prod`
+- `.runtime/dev`
+
+It must not commit or generate secrets. The provider and model are explicit;
+use `npm run init -- --provider openai --model <model-id>` for OpenAI.
+
+## 3. Secrets And Generated State
+
+Before publishing, confirm the repository does not include:
+
+- `.env`
+- `runtime.config.json`
+- `local/runtime.config.json`
+- `.runtime/`
+- `logs/`
+- `sessions/`
+- `dist/`
+- `memory/`
+- `*.bak`
+- `*:Zone.Identifier`
+
+Secrets are referenced by environment variable name only, for example
+`OPENAI_API_KEY` and `AGENT_BRIDGE_TOKEN`.
+
+## 4. Package Surface
+
+The public library surface is the package `exports` map. Hosts should not import
+internal runtime files directly. The installed command surface is the `abot`
+binary with its documented `init`, `add-model`, and `start` commands.
+
+Source-checkout scripts such as `npm run dev`, `npm run model-gateway`, and
+`npm run web-ui` are repository tooling; they are not installed CLI commands.
+Package consumers should use `npx abot`.
+
+Inside the verified public snapshot, run:
+
+```bash
+npm run check:runtime-package
+npm run check:publication
+```
+
+`check:runtime-package` validates the packed artifact. `check:publication`
+validates public repo hygiene. For a public package, the packed-artifact check
+also rejects any plugin set other than the exact public allowlist.
+
+## 5. Examples And Docs
+
+Keep these public onboarding files in sync:
+
+- `README.md`
+- `docs/installation.md`
+- `docs/configuration.md`
+- `docs/running-locally.md`
+- `docs/architecture.md`
+- `docs/bridge-compatibility.md`
+- `docs/known-limitations.md`
+- `docs/plugins.md`
+- `docs/troubleshooting.md`
+- `examples/minimal-runtime-composition.ts`
+- `examples/runtime.config.example.json`
+- `plugins/`
+
+Example config must stay sanitized and must not include host-specific URLs
+except local development defaults.
+
+## 6. Initial Public Repository Export
+
+From a clean, fully tracked private checkout, build a new snapshot into an
+empty directory:
+
+```bash
+npm run validate
+npm run build:public-snapshot -- --output /absolute/path/to/empty/public-snapshot
+```
+
+`build:public-snapshot` is a private-source export command. It is intentionally
+absent from the exported public package and must not become part of the public
+repository's normal development workflow.
+
+Use the snapshot once to seed the public Git repository. The generated
+`PUBLIC-SNAPSHOT.json` records that export; ordinary public changes do not
+rewrite or verify its frozen file hashes.
+
+## 7. Public Repository Releases
+
+After the initial export, maintain and release directly from the public Git
+repository:
+
+```bash
+npm ci
+npm run validate
+npm pack --dry-run
+```
+
+The public package explicitly sets `private: false`; the private development
+checkout explicitly sets `private: true`. Public `check:publication` validates
+the current repository rather than the initial export receipt. Tag or run
+`npm publish` only after current-tree validation and artifact review succeed on
+the real release machine.