@abot-ai/runtime 1.0.0

package/examples/runtime-library-host.ts

@@ -0,0 +1,24 @@
+import {
+  createDefaultRuntimeDependencies,
+  loadRuntimeConfig,
+} from "@abot-ai/runtime/runtime";
+
+const config = loadRuntimeConfig({ rootDir: process.cwd() });
+const runtime = createDefaultRuntimeDependencies(config);
+
+const handle = runtime.host.start({
+  runtimeConfig: config,
+  runtimeId: config.runtimeId,
+  agentBridgeUrl: config.agentBridgeUrl,
+  agentBridgeToken: config.agentBridgeToken,
+  eventSinkFactory: runtime.events,
+  modelGatewayClient: runtime.models,
+  sessionStore: runtime.sessions,
+  attachmentStore: runtime.attachments,
+  toolRegistry: runtime.tools,
+});
+
+process.on("SIGINT", async () => {
+  await handle.stop();
+  process.exit(0);
+});

package/examples/runtime.config.example.json

@@ -0,0 +1,63 @@
+{
+  "agentBridgeUrl": "ws://127.0.0.1:8787/abot/agent-bridge",
+  "modelGatewayUrl": "http://127.0.0.1:3000",
+  "environment": {
+    "default": "prod",
+    "paths": {
+      "sharedDir": ".runtime/shared",
+      "compiledDir": ".runtime/compiled",
+      "workspaceDir": "workspace"
+    },
+    "profiles": {
+      "prod": {
+        "paths": {
+          "runtimeDir": ".runtime/prod",
+          "agentWorkDir": ".runtime/prod/agent-work",
+          "sessionsDir": ".runtime/prod/sessions",
+          "attachmentsDir": ".runtime/prod/attachments"
+        }
+      },
+      "dev": {
+        "paths": {
+          "runtimeDir": ".runtime/dev",
+          "agentWorkDir": ".runtime/dev/agent-work",
+          "sessionsDir": ".runtime/dev/sessions",
+          "attachmentsDir": ".runtime/dev/attachments"
+        }
+      }
+    }
+  },
+  "webUi": {
+    "openOnRuntimeServiceStart": false
+  },
+  "logging": {
+    "enabled": true,
+    "rotation": {
+      "maxFileSizeMb": 20,
+      "maxFiles": 10,
+      "maxAgeDays": 7
+    }
+  },
+  "plugins": {
+    "enabled": true,
+    "allow": ["*"],
+    "deny": []
+  },
+  "models": {
+    "providers": {
+      "provider": {
+        "type": "ollama",
+        "baseUrl": "http://127.0.0.1:11434",
+        "keepAlive": "3m"
+      }
+    },
+    "profiles": {
+      "default": {
+        "configRef": "./models/default.config.json"
+      }
+    }
+  },
+  "requestRunner": {
+    "configRef": "./request-runner.config.json"
+  }
+}

package/package.json

@@ -0,0 +1,169 @@
+{
+  "bin": {
+    "abot": "./dist/src/cli/bin.js"
+  },
+  "bugs": {
+    "url": "https://github.com/Dorshitrit/abot-runtime/issues"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.29.8",
+    "@types/ws": "^8.18.1",
+    "@vscode/ripgrep": "1.18.0",
+    "dotenv": "^17.4.1",
+    "jszip": "^3.10.1",
+    "pdf-parse": "2.4.5",
+    "postcss": "^8.5.26",
+    "ws": "^8.21.0"
+  },
+  "description": "Open runtime for local AI agents.",
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "esbuild": "^0.27.7",
+    "prettier": "^3.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/src/runtime/index.js",
+      "types": "./dist/src/runtime/index.d.ts"
+    },
+    "./model-gateway": {
+      "import": "./dist/src/model-gateway/index.js",
+      "types": "./dist/src/model-gateway/index.d.ts"
+    },
+    "./package.json": "./package.json",
+    "./plugin-sdk": {
+      "import": "./dist/src/plugin-sdk/index.js",
+      "types": "./dist/src/plugin-sdk/index.d.ts"
+    },
+    "./runtime": {
+      "import": "./dist/src/runtime/index.js",
+      "types": "./dist/src/runtime/index.d.ts"
+    },
+    "./runtime.config.schema.json": "./runtime.config.schema.json",
+    "./runtime/adapters": {
+      "import": "./dist/src/runtime/adapters/index.js",
+      "types": "./dist/src/runtime/adapters/index.d.ts"
+    },
+    "./runtime/composition": {
+      "import": "./dist/src/runtime/composition.js",
+      "types": "./dist/src/runtime/composition.d.ts"
+    },
+    "./runtime/config": {
+      "import": "./dist/src/runtime/config.js",
+      "types": "./dist/src/runtime/config.d.ts"
+    },
+    "./runtime/default-adapters": {
+      "import": "./dist/src/runtime/default-adapters.js",
+      "types": "./dist/src/runtime/default-adapters.d.ts"
+    },
+    "./runtime/ports": {
+      "import": "./dist/src/runtime/ports.js",
+      "types": "./dist/src/runtime/ports.d.ts"
+    }
+  },
+  "files": [
+    "dist/scripts/",
+    "dist/src/cli/",
+    "dist/src/runtime/",
+    "dist/src/bridge/",
+    "dist/src/sessions/",
+    "dist/src/shared/",
+    "dist/src/capabilities/",
+    "dist/src/workspace/",
+    "dist/src/model-gateway/",
+    "dist/src/plugin-contract/",
+    "dist/src/plugin-sdk/",
+    "dist/src/web-ui/",
+    "runtime.config.schema.json",
+    "src/runtime/README.md",
+    "LICENSE",
+    "docs/architecture.md",
+    "docs/bridge-compatibility.md",
+    "docs/configuration.md",
+    "docs/installation.md",
+    "docs/known-limitations.md",
+    "docs/plugins.md",
+    "docs/publishing.md",
+    "docs/running-locally.md",
+    "docs/runtime-invariant-coverage.md",
+    "docs/runtime-library.md",
+    "docs/runtime-prompt-policy-contracts.md",
+    "docs/runtime-public-contracts.md",
+    "docs/tool-execution-result-evidence-contract.md",
+    "docs/troubleshooting.md",
+    "examples/minimal-runtime-composition.ts",
+    "examples/runtime-library-host.ts",
+    "examples/runtime.config.example.json",
+    "examples/env.example",
+    "examples/models/",
+    "examples/request-runner.config.example.json",
+    "plugins/capability-brief/",
+    "plugins/code-outline/",
+    "plugins/document-reader/",
+    "plugins/exec/",
+    "plugins/filesystem/",
+    "plugins/json-inspector/",
+    "plugins/local-search/",
+    "plugins/memory/",
+    "plugins/project-orientation/",
+    "plugins/system-probe/",
+    "plugins/web/"
+  ],
+  "homepage": "https://github.com/Dorshitrit/abot-runtime#readme",
+  "keywords": [
+    "llm",
+    "runtime",
+    "agents",
+    "tools",
+    "plugins",
+    "typescript"
+  ],
+  "license": "MIT",
+  "llmRuntime": {
+    "configSchema": "./runtime.config.schema.json"
+  },
+  "main": "./dist/src/runtime/index.js",
+  "name": "@abot-ai/runtime",
+  "overrides": {
+    "postcss": "^8.5.26"
+  },
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dorshitrit/abot-runtime.git"
+  },
+  "scripts": {
+    "add-model": "tsx scripts/add-runtime-model.ts",
+    "build": "npm run check:model-step-registry && npm run build-config-schema && npm run typecheck:plugins && npm run build:plugins && npm run clean-dist && tsc -p tsconfig.build.json && npm run copy-build-assets",
+    "build-config-schema": "tsx scripts/write-runtime-config-schema.ts",
+    "build:plugins": "tsx scripts/build-public-plugins.ts --write",
+    "check:model-step-registry": "tsx scripts/write-model-step-registry.ts --check",
+    "check:plugin-build": "npm run typecheck:plugins && tsx scripts/build-public-plugins.ts --check",
+    "check:plugins": "tsx scripts/check-plugins.ts",
+    "check:publication": "tsx scripts/check-publication-readiness.ts",
+    "check:runtime-package": "tsx scripts/check-runtime-package-contents.ts",
+    "clean-dist": "tsx scripts/clean-dist.ts",
+    "clean:dev-state": "tsx scripts/clean-dev-state.ts",
+    "copy-build-assets": "tsx scripts/copy-build-assets.ts",
+    "dev": "tsx index.ts",
+    "generate:model-step-registry": "tsx scripts/write-model-step-registry.ts",
+    "init": "tsx scripts/init-runtime.ts",
+    "model-gateway": "tsx src/model-gateway/server.ts",
+    "smoke:packed-runtime-package": "tsx scripts/smoke-packed-runtime-package.ts",
+    "smoke:runtime-package": "tsx scripts/smoke-runtime-package-import.ts",
+    "test": "vitest",
+    "typecheck:plugins": "tsc -p tsconfig.plugins.json",
+    "validate": "npm run check:plugin-build && npm test -- --run && npm run build && npm run check:plugins && npm run smoke:runtime-package && npm run check:runtime-package && npm run smoke:packed-runtime-package && npm run check:publication",
+    "web-ui": "tsx src/web-ui/server.ts",
+    "web-ui:install-user-services": "tsx scripts/install-runtime-web-ui-user-services.ts"
+  },
+  "type": "module",
+  "types": "./dist/src/runtime/index.d.ts",
+  "version": "1.0.0"
+}

package/plugins/capability-brief/plugin.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "capability-brief",
+  "version": "1.0.0",
+  "description": "Describe the request-effective ABot tool catalog on demand.",
+  "extensions": {
+    "ai.abot.runtime": {
+      "version": 1,
+      "entrypoint": "./src/index.cjs",
+      "catalogGroups": ["available-agent-tools"],
+      "capabilities": {
+        "capability_brief": {
+          "description": "Use this capability when the user asks what you can do, which capabilities, tools, or plugins are available, or which actions you can perform. Invoke it before answering and base the answer on the returned request-effective catalog; do not guess. Do not use it for ordinary task execution.",
+          "routingCapability": "semantic_lookup",
+          "skills": [],
+          "operations": {
+            "describe_available_tools": {
+              "summary": "List the tools and actions enabled for this request so you can answer what you can do. Invoke it before answering capability questions and do not guess.",
+              "input": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {},
+                "required": []
+              },
+              "effect": "read_only",
+              "approval": "request_policy"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/plugins/capability-brief/source/index.ts

@@ -0,0 +1,84 @@
+import {
+  boundCollection,
+  boundText,
+  defineRuntimePlugin,
+  failureResult,
+  successResult,
+  type ToolAvailabilityEntry,
+  type ToolExecutionContext,
+} from "../../../src/plugin-sdk/index.js";
+
+const TOOL_COUNT_MAX = 64;
+const OUTPUT_CHARACTER_MAX = 16_000;
+
+export default defineRuntimePlugin(() => ({
+  handlers: {
+    async capability_brief(
+      _params: Record<string, unknown>,
+      executionContext?: ToolExecutionContext,
+    ) {
+      const availableTools = executionContext?.sharedState?.availableTools;
+      if (availableTools === undefined) {
+        return failureResult({
+          errorCode: "available_tool_catalog_unavailable",
+          message: "The request-effective tool catalog is unavailable.",
+        });
+      }
+
+      const orderedTools = [...availableTools].sort(compareAvailableTools);
+      const boundedTools = boundCollection(orderedTools, {
+        maxItems: TOOL_COUNT_MAX,
+      });
+      const rawOutput = [
+        `Available tool operations: ${availableTools.length}`,
+        ...boundedTools.items.map(formatAvailableTool),
+        ...(boundedTools.metadata.truncated
+          ? [
+              `[${boundedTools.metadata.omittedItems} additional tool operations omitted]`,
+            ]
+          : []),
+      ].join("\n");
+      const boundedOutput = boundText(rawOutput, {
+        maxChars: OUTPUT_CHARACTER_MAX,
+        marker: "\n[available tool brief truncated]",
+      });
+
+      return successResult({
+        output: boundedOutput.text,
+        producedNewInformation: true,
+        data: {
+          source: "request_effective_tool_registry",
+          toolOperationCount: availableTools.length,
+          collection: boundedTools.metadata,
+          output: boundedOutput.metadata,
+          observationMeta: {
+            kind: "stable_fact",
+            carryPolicy: "never",
+          },
+        },
+      });
+    },
+  },
+}));
+
+function formatAvailableTool(tool: ToolAvailabilityEntry): string {
+  return [
+    `- ${tool.operationId}`,
+    `(tool=${tool.toolName}; effect=${tool.effect}; groups=${tool.catalogGroups.join(",")})`,
+    tool.summary,
+  ].join(" ");
+}
+
+function compareAvailableTools(
+  left: ToolAvailabilityEntry,
+  right: ToolAvailabilityEntry,
+): number {
+  const byOperation = compareAscii(left.operationId, right.operationId);
+  return byOperation !== 0
+    ? byOperation
+    : compareAscii(left.toolName, right.toolName);
+}
+
+function compareAscii(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/plugins/capability-brief/src/index.cjs

@@ -0,0 +1,194 @@
+// GENERATED FILE - DO NOT EDIT.
+// Source: plugins/capability-brief/source/index.ts
+// Run "npm run build:plugins" after editing plugin source.
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// plugins/capability-brief/source/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/plugin-sdk/bounds.ts
+function boundText(value, options) {
+  if (!Number.isSafeInteger(options.maxChars) || options.maxChars < 0) {
+    throw new RangeError("maxChars must be a non-negative safe integer");
+  }
+  const marker = options.marker ?? "\n[truncated]";
+  const truncated = value.length > options.maxChars;
+  const boundedMarker = marker.slice(0, options.maxChars);
+  const sourceChars = truncated ? Math.max(options.maxChars - boundedMarker.length, 0) : value.length;
+  const text = truncated ? value.slice(0, sourceChars) + boundedMarker : value;
+  return Object.freeze({
+    text,
+    metadata: Object.freeze({
+      truncated,
+      originalChars: value.length,
+      returnedChars: text.length,
+      omittedChars: Math.max(value.length - sourceChars, 0)
+    })
+  });
+}
+function boundCollection(values, options) {
+  if (!Number.isSafeInteger(options.maxItems) || options.maxItems < 0) {
+    throw new RangeError("maxItems must be a non-negative safe integer");
+  }
+  const items = Object.freeze(values.slice(0, options.maxItems));
+  return Object.freeze({
+    items,
+    metadata: Object.freeze({
+      truncated: values.length > items.length,
+      totalItems: values.length,
+      returnedItems: items.length,
+      omittedItems: values.length - items.length
+    })
+  });
+}
+
+// src/plugin-sdk/plugin.ts
+function defineRuntimePlugin(definition) {
+  return definition;
+}
+
+// src/plugin-sdk/results.ts
+var PLUGIN_RESULT_SERIALIZED_MAX_BYTES = 128 * 1024;
+function resultBoundsFailure(code, message) {
+  return {
+    ok: false,
+    output: message,
+    producedNewInformation: false,
+    error: message,
+    errorCode: code
+  };
+}
+function enforcePluginResultByteBudget(result) {
+  let serialized;
+  try {
+    const candidate = JSON.stringify(result);
+    if (candidate === void 0) {
+      return resultBoundsFailure(
+        "plugin_result_not_json_safe",
+        "The plugin produced a result that is not JSON-safe."
+      );
+    }
+    serialized = candidate;
+  } catch {
+    return resultBoundsFailure(
+      "plugin_result_not_json_safe",
+      "The plugin produced a result that is not JSON-safe."
+    );
+  }
+  if (Buffer.byteLength(serialized, "utf8") > PLUGIN_RESULT_SERIALIZED_MAX_BYTES) {
+    return resultBoundsFailure(
+      "plugin_result_too_large",
+      `The plugin result exceeds the ${PLUGIN_RESULT_SERIALIZED_MAX_BYTES}-byte safety limit.`
+    );
+  }
+  return result;
+}
+function successResult(input) {
+  return enforcePluginResultByteBudget({
+    ok: true,
+    output: input.output,
+    producedNewInformation: input.producedNewInformation ?? true,
+    ...input.progress !== void 0 ? { progress: input.progress } : {},
+    ...input.actions !== void 0 ? { actions: input.actions } : {},
+    ...input.exitCode !== void 0 ? { exitCode: input.exitCode } : {},
+    ...input.stdout !== void 0 ? { stdout: input.stdout } : {},
+    ...input.stderr !== void 0 ? { stderr: input.stderr } : {},
+    ...input.data !== void 0 ? { data: input.data } : {}
+  });
+}
+function failureResult(input) {
+  return enforcePluginResultByteBudget({
+    ok: false,
+    output: input.output ?? input.message,
+    producedNewInformation: false,
+    ...input.progress !== void 0 ? { progress: input.progress } : {},
+    ...input.actions !== void 0 ? { actions: input.actions } : {},
+    ...input.exitCode !== void 0 ? { exitCode: input.exitCode } : {},
+    ...input.stdout !== void 0 ? { stdout: input.stdout } : {},
+    ...input.stderr !== void 0 ? { stderr: input.stderr } : {},
+    ...input.data !== void 0 ? { data: input.data } : {},
+    error: input.message,
+    errorCode: input.errorCode
+  });
+}
+
+// plugins/capability-brief/source/index.ts
+var TOOL_COUNT_MAX = 64;
+var OUTPUT_CHARACTER_MAX = 16e3;
+var index_default = defineRuntimePlugin(() => ({
+  handlers: {
+    async capability_brief(_params, executionContext) {
+      const availableTools = executionContext?.sharedState?.availableTools;
+      if (availableTools === void 0) {
+        return failureResult({
+          errorCode: "available_tool_catalog_unavailable",
+          message: "The request-effective tool catalog is unavailable."
+        });
+      }
+      const orderedTools = [...availableTools].sort(compareAvailableTools);
+      const boundedTools = boundCollection(orderedTools, {
+        maxItems: TOOL_COUNT_MAX
+      });
+      const rawOutput = [
+        `Available tool operations: ${availableTools.length}`,
+        ...boundedTools.items.map(formatAvailableTool),
+        ...boundedTools.metadata.truncated ? [
+          `[${boundedTools.metadata.omittedItems} additional tool operations omitted]`
+        ] : []
+      ].join("\n");
+      const boundedOutput = boundText(rawOutput, {
+        maxChars: OUTPUT_CHARACTER_MAX,
+        marker: "\n[available tool brief truncated]"
+      });
+      return successResult({
+        output: boundedOutput.text,
+        producedNewInformation: true,
+        data: {
+          source: "request_effective_tool_registry",
+          toolOperationCount: availableTools.length,
+          collection: boundedTools.metadata,
+          output: boundedOutput.metadata,
+          observationMeta: {
+            kind: "stable_fact",
+            carryPolicy: "never"
+          }
+        }
+      });
+    }
+  }
+}));
+function formatAvailableTool(tool) {
+  return [
+    `- ${tool.operationId}`,
+    `(tool=${tool.toolName}; effect=${tool.effect}; groups=${tool.catalogGroups.join(",")})`,
+    tool.summary
+  ].join(" ");
+}
+function compareAvailableTools(left, right) {
+  const byOperation = compareAscii(left.operationId, right.operationId);
+  return byOperation !== 0 ? byOperation : compareAscii(left.toolName, right.toolName);
+}
+function compareAscii(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/plugins/code-outline/plugin.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "code-outline",
+  "version": "0.1.1",
+  "description": "Extract a bounded structural outline from one source file.",
+  "extensions": {
+    "ai.abot.runtime": {
+      "version": 1,
+      "entrypoint": "./src/index.cjs",
+      "catalogGroups": ["read"],
+      "settings": {
+        "defaults": {
+          "defaultMaxSymbols": 160
+        }
+      },
+      "capabilities": {
+        "inspect_code_outline": {
+          "description": "Extract a bounded outline of symbols, selectors, elements, and imports from one source file beneath the configured agent work directory or configured workspace sources, without returning the full file.",
+          "routingCapability": "semantic_lookup",
+          "runtimePathBindings": [
+            {
+              "operationId": "inspect_code_outline",
+              "param": "path",
+              "base": "worker_working_directory"
+            }
+          ],
+          "skills": ["code_outline_skill"],
+          "operations": {
+            "inspect_code_outline": {
+              "summary": "Inspect symbols and dependencies in one bounded source file.",
+              "input": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1024
+                  },
+                  "maxSymbols": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 160
+                  }
+                },
+                "required": ["path"]
+              },
+              "effect": "read_only",
+              "approval": "request_policy"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/plugins/code-outline/skills/code_outline_skill/SKILL.md

@@ -0,0 +1,9 @@
+# Code Outline Skill
+
+Use `inspect_code_outline` when an unfamiliar source file's structure must be
+understood before a focused read or edit. Prefer it over repeatedly reading a
+large file with no target. It returns symbols and imports without the full
+source; use exact current line context before mutation.
+
+Relative paths resolve beneath the configured agent work directory. Use
+`workspace/...` only for configured workspace sources.