@abot-ai/runtime 1.0.0

package/dist/src/workspace/files.d.ts

@@ -0,0 +1,4 @@
+import type { WorkspaceSourceFile } from "./types.js";
+export declare function readWorkspaceMarkdownFiles(workspaceDir: string): Promise<WorkspaceSourceFile[]>;
+export declare function buildWorkspaceSourceHash(files: WorkspaceSourceFile[]): string;
+export declare function buildDeterministicWorkspaceConcat(files: WorkspaceSourceFile[]): string;

package/dist/src/workspace/files.js

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+async function collectMarkdownFiles(rootDir, currentDir) {
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            const nested = await collectMarkdownFiles(rootDir, fullPath);
+            files.push(...nested);
+            continue;
+        }
+        if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+            files.push(relative(rootDir, fullPath).replaceAll("\\", "/"));
+        }
+    }
+    return files;
+}
+export async function readWorkspaceMarkdownFiles(workspaceDir) {
+    await mkdir(workspaceDir, { recursive: true });
+    const relPaths = await collectMarkdownFiles(workspaceDir, workspaceDir);
+    const files = [];
+    for (const relPath of relPaths) {
+        const content = await readFile(join(workspaceDir, relPath), "utf-8");
+        files.push({ path: relPath, content });
+    }
+    return files;
+}
+export function buildWorkspaceSourceHash(files) {
+    const hash = createHash("sha256");
+    for (const file of files) {
+        hash.update(file.path);
+        hash.update("\n");
+        hash.update(file.content);
+        hash.update("\n---\n");
+    }
+    return hash.digest("hex");
+}
+export function buildDeterministicWorkspaceConcat(files) {
+    const parts = [];
+    for (const file of files) {
+        parts.push(`### FILE: ${file.path}`);
+        parts.push(file.content);
+        parts.push("");
+    }
+    return parts.join("\n");
+}

package/dist/src/workspace/types.d.ts

@@ -0,0 +1,10 @@
+export type WorkspaceSourceFile = {
+    path: string;
+    content: string;
+};
+export type CompiledWorkspaceSummary = {
+    sourceHash: string;
+    generatedAt: string;
+    files: string[];
+    summary: string;
+};

package/dist/src/workspace/types.js

@@ -0,0 +1 @@
+export {};

package/docs/architecture.md

@@ -0,0 +1,134 @@
+# Architecture
+
+`abot` is a local, embeddable runtime for model-driven requests. It has one
+request kernel for conversation, delegated reasoning, tools, artifact work,
+and follow-up requests. A model profile selects one registered root contract;
+it does not select another runner or state machine.
+
+## Request Path
+
+```text
+client or host
+  -> RuntimeHost
+  -> request handler
+  -> canonical root kernel
+       -> Supervisor contract or Execution Agent contract
+       -> optional registered subordinate calls
+       -> policy-authorized capability execution
+       -> exact child results return to their caller
+  -> root response
+  -> request finalizer
+```
+
+The canonical root always starts and ends the semantic request. The default
+Supervisor contract may respond directly or delegate one bounded objective.
+The opt-in Execution Agent contract may execute capabilities directly. The
+runtime never chooses a route from prompt words, paths, tool names, or task
+categories.
+
+## Role Model
+
+- **Canonical root** owns the root request and final user response.
+- **Supervisor** is the default delegated model contract for that root.
+- **Execution Agent** is the opt-in direct-capability contract for the same
+  root and kernel.
+- **Planner** coordinates a bounded sub-process through child role calls.
+- **Worker** produces a bounded result and owns concrete capability selection.
+- **Reviewer** audits supplied work and returns advisory findings to its caller.
+
+The active role model proposes one strict semantic action. Runtime orchestration
+validates and executes that exact action, commits it to the role-call ledger,
+and returns child results to the exact caller.
+
+## Canonical Ownership
+
+- `src/runtime/request/` owns the external request boundary, shared root kernel,
+  policy composition, and client-facing plan projection.
+- `src/runtime/orchestration/role-calls/` is the sole writer of call frames and
+  role results.
+- `src/runtime/orchestration/role-executors/` mechanically invokes configured
+  non-Supervisor roles.
+- `src/runtime/orchestration/worker-capabilities/` is the shared capability
+  engine and binds selection, execution, payloads, and settled results to the
+  exact policy-authorized call.
+- `src/runtime/steps/` owns strict model instructions, schemas, parsing, and
+  diagnostics for each role.
+- `src/runtime/lifecycle/` owns final persistence and request completion.
+
+Events project committed state; they never become a second progress store.
+
+## Tool and Plugin Boundary
+
+Built-in and plugin tools enter one config-filtered `ToolRegistry`. A
+policy-authorized model contract sees public normal-invocation contracts and
+may select a capability when its objective requires an external observation or
+effect. Runtime adapters validate controls, approval, payload, and execution
+without deciding the next role or overall completion.
+
+Concrete tool behavior belongs in the tool or plugin. Filesystem and process
+policy belongs in their adapters. Core orchestration must not branch on a
+specific capability identity.
+
+## Client Events
+
+Planner child-call commits are projected through the existing
+`planner.plan.*` event family. For client compatibility those payloads retain
+`stage=development_plan`, even though the runtime no longer has a Development
+loop. Tool execution keeps the existing `tool.*` event lifecycle.
+
+## Configuration
+
+Runtime config owns installed models, plugin availability, environments, and
+the request-runner config reference. Plugin packages own every concrete tool
+and skill declaration. The request-runner config owns model-step mappings,
+context budgets, and step timeouts only. It does not configure a role
+hierarchy, work profile, or fixed role sequence.
+
+Environment profiles isolate generated state. Model profiles select providers
+and calibration, and may select one code-owned `execution.policy`. Omission
+uses `supervisor-worker-v1`; `execution-agent-v1` is an explicit opt-in. Both
+reuse the same kernel, ledger, reducer, capability engine, and finalizer.
+
+## Composition and Public Boundary
+
+Hosts compose the runtime through public package entrypoints:
+
+```ts
+import {
+  createRuntimeApplication,
+  loadRuntimeConfig,
+} from "@abot-ai/runtime/runtime";
+
+const config = loadRuntimeConfig({ rootDir: process.cwd() });
+const runtime = createRuntimeApplication(config);
+await runtime.host.start();
+```
+
+`RuntimeApplication` owns one environment service graph and one bound request
+handler. A request then owns one `RequestHandlingSession`, immutable
+`RequestExecutionScope`, model-step invoker, role-call ledger/transactions,
+and capability runtime. Compatibility facades may expose legacy flat fields,
+but those fields are getter views of the same request-owned facets rather than
+separately assembled state.
+
+The root kernel, role activation loop, capability binding, payload-stage
+runner, model invocation, and stream accumulator are lifetime-specific owners
+over the same mechanisms. No request-scoped object is reachable through a
+global request ID lookup. Process debug and model-I/O loggers remain explicit
+process singletons to preserve existing trace routing.
+
+Internal request, orchestration, role-step, model, context, and event modules
+are not public API. Session state and request replay remain runtime-owned; a
+bridge or UI may relay events but is not the source of truth.
+
+## Generated State
+
+Generated local state is ignored by git:
+
+- `.runtime/`
+- `logs/`
+- `sessions/`
+- `dist/`
+
+Do not publish local sessions, logs, memory, artifacts, or machine-specific
+configuration.

package/docs/bridge-compatibility.md

@@ -0,0 +1,128 @@
+# Bridge Compatibility
+
+`abot` can be embedded directly by a host application or connected to a
+bridge service. The bridge is transport infrastructure. It should not own the
+runtime state model.
+
+The source-checkout Web UI uses the direct local runtime transport by default.
+This is separate from the external bridge path, so private clients that use
+their own bridge can keep using the existing bridge protocol.
+
+## Ownership
+
+The runtime owns:
+
+- session storage
+- request event persistence
+- replayable request state
+- final assistant output
+- tool routing and execution
+- model calls through the configured gateway
+
+The bridge owns:
+
+- client connectivity
+- authentication at the transport edge
+- live event delivery
+- request forwarding
+- reconnect and delivery mechanics
+
+Clients should be able to recover from runtime-backed session snapshots and
+request replay after reconnecting.
+
+## `runtimeId` And Legacy `agentId`
+
+Runtime config and public examples use `runtimeId` to identify the running
+runtime instance or environment.
+
+Some bridge-facing protocol fields may still be named `agentId` for
+compatibility with existing bridge clients. That field name is transport
+compatibility only. It does not mean the runtime has a multi-agent management
+model.
+
+When adapting a bridge:
+
+- map the runtime's `runtimeId` to the bridge protocol field expected by the
+  bridge
+- keep environment names as `prod`, `dev`, or another host-defined profile
+- do not introduce agent names such as `main` unless the host actually has an
+  agent-management layer
+- keep request/session source of truth inside the runtime
+
+## Expected Flow
+
+```text
+client
+  -> bridge transport
+  -> runtime host
+  -> runtime sessions/events/tools/model gateway
+```
+
+The bridge may cache live delivery state, but durable recovery should come from
+runtime-owned session and request state.
+
+## Active Request Steering
+
+Runtime bridge registration advertises optional protocol features. When
+`request_steering_v1` is present, the bridge may forward a later user message
+to the same active request:
+
+```json
+{
+  "type": "steer_request",
+  "requestId": "request-id",
+  "steerId": "client-idempotency-id",
+  "text": "Use the shorter format instead"
+}
+```
+
+The runtime responds with a correlated `steer_ack` and an
+`acceptedSequence`, or rejects it when the request is no longer active. The
+runtime preserves message order and idempotency but does not interpret whether
+the message means refine, redirect, add work, or stop. That remains a model
+decision at the next safe model boundary.
+
+Capability discovery is automatic: clients keep their legacy queue behavior
+while the feature is absent and may enable steering after the runtime
+reconnects and advertises it. No separate runtime flag or client refresh is
+required.
+
+## Web UI Transport
+
+The Web UI server supports two transport backends:
+
+- `runtime`: direct local in-process runtime transport. This is the default.
+- `bridge`: compatibility proxy to an external bridge that implements the
+  runtime bridge HTTP and realtime contract.
+
+Select the bridge proxy explicitly:
+
+```bash
+LLM_RUNTIME_WEB_BACKEND=bridge npm run web-ui
+```
+
+The direct Web UI transport does not change bridge registration, bridge
+authentication, or private app traffic.
+
+## External Bridge Adapter Contract
+
+An external bridge can be private, public, local, or hosted. The runtime only
+requires it to expose the bridge transport configured for the Web UI:
+
+```text
+LLM_RUNTIME_WEB_BACKEND=bridge
+LLM_RUNTIME_WEB_API_BASE_URL=http://127.0.0.1:8787/abot/api
+LLM_RUNTIME_WEB_REALTIME_URL=ws://127.0.0.1:8787/abot/realtime
+LLM_RUNTIME_WEB_HEALTH_URL=http://127.0.0.1:8787/abot/health
+LLM_RUNTIME_WEB_AGENT_MODE_URL=http://127.0.0.1:8787/abot/agent-mode
+LLM_RUNTIME_WEB_API_TOKEN=<bridge token>
+```
+
+The Web UI forwards `/web-api/*` to the configured API base path, forwards
+`/web-realtime` to the configured realtime WebSocket, and forwards health and
+mode checks to their configured endpoints.
+
+For compatibility with bridge protocols that still use legacy naming, the
+external bridge adapter mirrors `environment` or `environmentId` into
+`agentId`. This compatibility mapping is isolated to the external bridge
+adapter; runtime config and public examples remain environment-based.