@robota-sdk/pack-coding 3.0.0-beta.100

package/README.md

@@ -0,0 +1,57 @@
+# @robota-sdk/pack-coding
+
+Robota's coding capability as a single
+[`ICapabilityPack`](../agent-capability-pack/README.md): the built-in coding tools, the coding command
+modules, and the coding subagents in one unit that `assembleProduct` can add to any product. The
+The host CLI can compose it for its coding assistant.
+
+## Installation
+
+```bash
+npm install @robota-sdk/pack-coding
+```
+
+## Usage
+
+```ts
+import { assembleProduct } from '@robota-sdk/agent-product';
+import { createCodingPack } from '@robota-sdk/pack-coding';
+import type { IAIProvider, IProviderDefinition } from '@robota-sdk/agent-core';
+
+declare const providerDefinitions: readonly IProviderDefinition[];
+declare const provider: IAIProvider;
+
+const cwd = process.cwd();
+const product = assembleProduct({
+  id: 'acme-assistant',
+  providerDefinitions,
+  // The coding tools, /shell + /editor + /git commands, and coding subagents. The file tools are
+  // scoped to the cwd you build the pack with.
+  packs: [createCodingPack({ cwd })],
+});
+
+const session = product.buildRuntime({ session: { cwd, provider } });
+void session;
+```
+
+The pack bundles:
+
+- **tools** — `Shell`, `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`, `WebSearch`,
+  `AskUserQuestion` (from `@robota-sdk/agent-tool-defaults`' `createDefaultTools`).
+- **commandModules** — `/shell`, `/editor`, and `/git` (from `@robota-sdk/agent-command`).
+- **subagents** — `general-purpose`, `Explore`, `Plan` (agent-framework's built-in agents).
+
+`createCodingPack` passes its `cwd` and optional `sandboxClient` straight to the default tool factory,
+so the pack adds, drops, or reorders none of those tools. Its other options are `shellExecutable` (the
+shell for the tools and `/shell`) and `editorTemporaryDirectoryPrefix` (for `/editor`).
+
+## Why a factory, and why `cwd` is required
+
+There is deliberately **no context-free `codingPack` constant**. The tool layer refuses a missing
+execution root, and this factory also requires `cwd` so each pack's file tools are scoped to the
+session that constructs it. That matters most when a product hands its whole tool surface to packs by
+passing `defaultTools: []` in the session options. See [`docs/SPEC.md`](./docs/SPEC.md).
+
+## License
+
+AGPL-3.0-only OR LicenseRef-Commercial

package/dist/node/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@robota-sdk/agent-command"),t=require("@robota-sdk/agent-framework"),n=require("@robota-sdk/agent-tool-defaults");function r(r){return{id:`coding`,title:`Coding`,description:`Built-in coding capability: file/shell tools, /shell + /editor + /git commands, and the coding subagents.`,tools:(0,n.createDefaultTools)({cwd:r.cwd,httpUserAgent:r.httpUserAgent,...r.shellExecutable===void 0?{}:{shellExecutable:r.shellExecutable},...r.sandboxClient?{sandboxClient:r.sandboxClient}:{},...r.editorFiles?{editorFiles:r.editorFiles}:{}}),commandModules:[(0,e.createShellCommandModule)(r.shellExecutable),(0,e.createEditorCommandModule)(r.editorTemporaryDirectoryPrefix),(0,e.createGitCommandModule)()],subagents:t.BUILT_IN_AGENTS}}exports.createCodingPack=r;

package/dist/node/index.d.cts

@@ -0,0 +1,74 @@
+import { ICapabilityPack } from "@robota-sdk/agent-capability-pack";
+import { IEditorFileAccess, ISandboxClient } from "@robota-sdk/agent-tools";
+//#region src/coding-pack.d.ts
+/**
+ * The session context agent's coding tools are bound to.
+ *
+ * `cwd` is **required, not optional** — and that is the whole point of this factory. `agent-tools`'
+ * `checkPathWithinCwd` USED TO BE a no-op when `cwd` was `undefined`, so file tools constructed with no
+ * options carried a DISARMED working-directory guard: their `Read` returned `/etc/hostname`. Before
+ * ARCH-006 that was inert, because the framework's own context-bound default tier always won a name
+ * collision. Once a product could hand the entire tool surface to its packs (`defaultTools: []`), a
+ * context-free pack became an unsandboxed `Read`/`Write`/`Edit`.
+ *
+ * ARCH-010 has since fixed the layer below: the guard refuses when no root is configured, and the tool
+ * factories require `cwd` themselves. This requirement is therefore no longer load-bearing on its own —
+ * it is the precedent the audit's fix followed, and it stays because the scoping decision should be
+ * impossible to forget at every layer, not only the lowest one.
+ */
+interface ICodingPackOptions {
+  /** Product-host shell choice for tools and the interactive /shell command. */
+  shellExecutable?: string;
+  /** HTTP identity selected by the product host. */
+  httpUserAgent?: string;
+  /** Product-owned prefix for the interactive editor's temporary directory. */
+  editorTemporaryDirectoryPrefix?: string;
+  /**
+   * Working-directory root the host file tools (`Read`/`Write`/`Edit`) are restricted to. Required: see
+   * the interface note above. Pass the same value the session is assembled with.
+   */
+  cwd: string;
+  /**
+   * Optional provider sandbox client. Shell commands always run through it; file tools do only when its
+   * filesystem is `separate` (then the sandbox is the isolation boundary and the host-only search tools
+   * are withheld). With a `shared` filesystem, file tools stay on the host under the path guard.
+   */
+  sandboxClient?: ISandboxClient;
+  /**
+   * An editor that has the workspace open, asked at each call: the host file tools read and write
+   * through what it offers. Absent, or answering `undefined`, means the disk.
+   */
+  editorFiles?: () => IEditorFileAccess | undefined;
+}
+/**
+ * Build agent's coding capability as a single {@link ICapabilityPack}, bound to one session context.
+ *
+ * This is the additive-axis proof for ARCH-005 and agent's first capability pack: a pack can bundle
+ * agent's real coding capability (tools + command modules + subagents) and be composed additively by
+ * `assembleProduct` on top of any product's base — and, since ARCH-006, can OWN the product's tool surface
+ * outright when the profile suppresses the framework tier with `defaultTools: []`.
+ *
+ * - **tools** — `createDefaultTools()` from `@robota-sdk/agent-tool-defaults`, CONSUMED rather than
+ *   mirrored (ARCH-035). That set is shell/bash/read/write/edit/glob/grep/webFetch/webSearch/
+ *   askUserQuestion; the adapter-gated tools (`CodebaseRetrieval`, `Computer`) appear only when their
+ *   adapter or driver is supplied, and this pack supplies neither. Until ARCH-035 the list was rebuilt
+ *   here from the `@robota-sdk/agent-tools` factories and held to the defaults by a NAME-equality test
+ *   — a pin that let ARCH-021's first TC-05 pass while being unable to fail, because comparing names
+ *   cannot distinguish a pack-composed surface from an imported-default one when the two are pinned.
+ *   The relationship is structural now, so there is no drift left to pin.
+ * - **commandModules** — the coding command modules: `/shell`, `/editor` and `/git` (the capability-level
+ *   command modules, distinct from product-shell/settings/provider command infrastructure).
+ * - **subagents** — agent's built-in coding subagents (`general-purpose`, `Explore`, `Plan`).
+ *
+ * This pack contributes only when a product profile lists it (opt-in); every contributed command/tool runs
+ * only through the permission-gated runtime at call time.
+ *
+ * **Per-call instances, deliberately.** Each call builds fresh tool and command-module objects bound to the
+ * supplied context, so two products assembled in one process get independently-scoped file tools. There is
+ * no module-level singleton: a shared constant could only ever be context-free, which is exactly the hazard
+ * this factory exists to remove.
+ */
+declare function createCodingPack(options: ICodingPackOptions): ICapabilityPack;
+//#endregion
+export { type ICodingPackOptions, createCodingPack };
+//# sourceMappingURL=index.d.cts.map

package/dist/node/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/coding-pack.ts"],"mappings":";;;;;;;;;;;;;;;;;;UA0BiB;;EAEf;;EAEA;;EAEA;;;;;EAKA;;;;;;EAMA,gBAAgB;;;;;EAKhB,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BN,iBAAiB,SAAS,qBAAqB"}

package/dist/node/index.d.ts

@@ -0,0 +1,74 @@
+import { ICapabilityPack } from "@robota-sdk/agent-capability-pack";
+import { IEditorFileAccess, ISandboxClient } from "@robota-sdk/agent-tools";
+//#region src/coding-pack.d.ts
+/**
+ * The session context agent's coding tools are bound to.
+ *
+ * `cwd` is **required, not optional** — and that is the whole point of this factory. `agent-tools`'
+ * `checkPathWithinCwd` USED TO BE a no-op when `cwd` was `undefined`, so file tools constructed with no
+ * options carried a DISARMED working-directory guard: their `Read` returned `/etc/hostname`. Before
+ * ARCH-006 that was inert, because the framework's own context-bound default tier always won a name
+ * collision. Once a product could hand the entire tool surface to its packs (`defaultTools: []`), a
+ * context-free pack became an unsandboxed `Read`/`Write`/`Edit`.
+ *
+ * ARCH-010 has since fixed the layer below: the guard refuses when no root is configured, and the tool
+ * factories require `cwd` themselves. This requirement is therefore no longer load-bearing on its own —
+ * it is the precedent the audit's fix followed, and it stays because the scoping decision should be
+ * impossible to forget at every layer, not only the lowest one.
+ */
+interface ICodingPackOptions {
+  /** Product-host shell choice for tools and the interactive /shell command. */
+  shellExecutable?: string;
+  /** HTTP identity selected by the product host. */
+  httpUserAgent?: string;
+  /** Product-owned prefix for the interactive editor's temporary directory. */
+  editorTemporaryDirectoryPrefix?: string;
+  /**
+   * Working-directory root the host file tools (`Read`/`Write`/`Edit`) are restricted to. Required: see
+   * the interface note above. Pass the same value the session is assembled with.
+   */
+  cwd: string;
+  /**
+   * Optional provider sandbox client. Shell commands always run through it; file tools do only when its
+   * filesystem is `separate` (then the sandbox is the isolation boundary and the host-only search tools
+   * are withheld). With a `shared` filesystem, file tools stay on the host under the path guard.
+   */
+  sandboxClient?: ISandboxClient;
+  /**
+   * An editor that has the workspace open, asked at each call: the host file tools read and write
+   * through what it offers. Absent, or answering `undefined`, means the disk.
+   */
+  editorFiles?: () => IEditorFileAccess | undefined;
+}
+/**
+ * Build agent's coding capability as a single {@link ICapabilityPack}, bound to one session context.
+ *
+ * This is the additive-axis proof for ARCH-005 and agent's first capability pack: a pack can bundle
+ * agent's real coding capability (tools + command modules + subagents) and be composed additively by
+ * `assembleProduct` on top of any product's base — and, since ARCH-006, can OWN the product's tool surface
+ * outright when the profile suppresses the framework tier with `defaultTools: []`.
+ *
+ * - **tools** — `createDefaultTools()` from `@robota-sdk/agent-tool-defaults`, CONSUMED rather than
+ *   mirrored (ARCH-035). That set is shell/bash/read/write/edit/glob/grep/webFetch/webSearch/
+ *   askUserQuestion; the adapter-gated tools (`CodebaseRetrieval`, `Computer`) appear only when their
+ *   adapter or driver is supplied, and this pack supplies neither. Until ARCH-035 the list was rebuilt
+ *   here from the `@robota-sdk/agent-tools` factories and held to the defaults by a NAME-equality test
+ *   — a pin that let ARCH-021's first TC-05 pass while being unable to fail, because comparing names
+ *   cannot distinguish a pack-composed surface from an imported-default one when the two are pinned.
+ *   The relationship is structural now, so there is no drift left to pin.
+ * - **commandModules** — the coding command modules: `/shell`, `/editor` and `/git` (the capability-level
+ *   command modules, distinct from product-shell/settings/provider command infrastructure).
+ * - **subagents** — agent's built-in coding subagents (`general-purpose`, `Explore`, `Plan`).
+ *
+ * This pack contributes only when a product profile lists it (opt-in); every contributed command/tool runs
+ * only through the permission-gated runtime at call time.
+ *
+ * **Per-call instances, deliberately.** Each call builds fresh tool and command-module objects bound to the
+ * supplied context, so two products assembled in one process get independently-scoped file tools. There is
+ * no module-level singleton: a shared constant could only ever be context-free, which is exactly the hazard
+ * this factory exists to remove.
+ */
+declare function createCodingPack(options: ICodingPackOptions): ICapabilityPack;
+//#endregion
+export { type ICodingPackOptions, createCodingPack };
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/coding-pack.ts"],"mappings":";;;;;;;;;;;;;;;;;;UA0BiB;;EAEf;;EAEA;;EAEA;;;;;EAKA;;;;;;EAMA,gBAAgB;;;;;EAKhB,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BN,iBAAiB,SAAS,qBAAqB"}

package/dist/node/index.js

@@ -0,0 +1,2 @@
+import{createEditorCommandModule as e,createGitCommandModule as t,createShellCommandModule as n}from"@robota-sdk/agent-command";import{BUILT_IN_AGENTS as r}from"@robota-sdk/agent-framework";import{createDefaultTools as i}from"@robota-sdk/agent-tool-defaults";function a(a){return{id:`coding`,title:`Coding`,description:`Built-in coding capability: file/shell tools, /shell + /editor + /git commands, and the coding subagents.`,tools:i({cwd:a.cwd,httpUserAgent:a.httpUserAgent,...a.shellExecutable===void 0?{}:{shellExecutable:a.shellExecutable},...a.sandboxClient?{sandboxClient:a.sandboxClient}:{},...a.editorFiles?{editorFiles:a.editorFiles}:{}}),commandModules:[n(a.shellExecutable),e(a.editorTemporaryDirectoryPrefix),t()],subagents:r}}export{a as createCodingPack};
+//# sourceMappingURL=index.js.map

package/dist/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/coding-pack.ts"],"sourcesContent":["import {\n  createEditorCommandModule,\n  createGitCommandModule,\n  createShellCommandModule,\n} from '@robota-sdk/agent-command';\nimport { BUILT_IN_AGENTS } from '@robota-sdk/agent-framework';\nimport { createDefaultTools } from '@robota-sdk/agent-tool-defaults';\n\nimport type { ICapabilityPack } from '@robota-sdk/agent-capability-pack';\nimport type { IEditorFileAccess, ISandboxClient } from '@robota-sdk/agent-tools';\n\n/**\n * The session context agent's coding tools are bound to.\n *\n * `cwd` is **required, not optional** — and that is the whole point of this factory. `agent-tools`'\n * `checkPathWithinCwd` USED TO BE a no-op when `cwd` was `undefined`, so file tools constructed with no\n * options carried a DISARMED working-directory guard: their `Read` returned `/etc/hostname`. Before\n * ARCH-006 that was inert, because the framework's own context-bound default tier always won a name\n * collision. Once a product could hand the entire tool surface to its packs (`defaultTools: []`), a\n * context-free pack became an unsandboxed `Read`/`Write`/`Edit`.\n *\n * ARCH-010 has since fixed the layer below: the guard refuses when no root is configured, and the tool\n * factories require `cwd` themselves. This requirement is therefore no longer load-bearing on its own —\n * it is the precedent the audit's fix followed, and it stays because the scoping decision should be\n * impossible to forget at every layer, not only the lowest one.\n */\nexport interface ICodingPackOptions {\n  /** Product-host shell choice for tools and the interactive /shell command. */\n  shellExecutable?: string;\n  /** HTTP identity selected by the product host. */\n  httpUserAgent?: string;\n  /** Product-owned prefix for the interactive editor's temporary directory. */\n  editorTemporaryDirectoryPrefix?: string;\n  /**\n   * Working-directory root the host file tools (`Read`/`Write`/`Edit`) are restricted to. Required: see\n   * the interface note above. Pass the same value the session is assembled with.\n   */\n  cwd: string;\n  /**\n   * Optional provider sandbox client. Shell commands always run through it; file tools do only when its\n   * filesystem is `separate` (then the sandbox is the isolation boundary and the host-only search tools\n   * are withheld). With a `shared` filesystem, file tools stay on the host under the path guard.\n   */\n  sandboxClient?: ISandboxClient;\n  /**\n   * An editor that has the workspace open, asked at each call: the host file tools read and write\n   * through what it offers. Absent, or answering `undefined`, means the disk.\n   */\n  editorFiles?: () => IEditorFileAccess | undefined;\n}\n\n/**\n * Build agent's coding capability as a single {@link ICapabilityPack}, bound to one session context.\n *\n * This is the additive-axis proof for ARCH-005 and agent's first capability pack: a pack can bundle\n * agent's real coding capability (tools + command modules + subagents) and be composed additively by\n * `assembleProduct` on top of any product's base — and, since ARCH-006, can OWN the product's tool surface\n * outright when the profile suppresses the framework tier with `defaultTools: []`.\n *\n * - **tools** — `createDefaultTools()` from `@robota-sdk/agent-tool-defaults`, CONSUMED rather than\n *   mirrored (ARCH-035). That set is shell/bash/read/write/edit/glob/grep/webFetch/webSearch/\n *   askUserQuestion; the adapter-gated tools (`CodebaseRetrieval`, `Computer`) appear only when their\n *   adapter or driver is supplied, and this pack supplies neither. Until ARCH-035 the list was rebuilt\n *   here from the `@robota-sdk/agent-tools` factories and held to the defaults by a NAME-equality test\n *   — a pin that let ARCH-021's first TC-05 pass while being unable to fail, because comparing names\n *   cannot distinguish a pack-composed surface from an imported-default one when the two are pinned.\n *   The relationship is structural now, so there is no drift left to pin.\n * - **commandModules** — the coding command modules: `/shell`, `/editor` and `/git` (the capability-level\n *   command modules, distinct from product-shell/settings/provider command infrastructure).\n * - **subagents** — agent's built-in coding subagents (`general-purpose`, `Explore`, `Plan`).\n *\n * This pack contributes only when a product profile lists it (opt-in); every contributed command/tool runs\n * only through the permission-gated runtime at call time.\n *\n * **Per-call instances, deliberately.** Each call builds fresh tool and command-module objects bound to the\n * supplied context, so two products assembled in one process get independently-scoped file tools. There is\n * no module-level singleton: a shared constant could only ever be context-free, which is exactly the hazard\n * this factory exists to remove.\n */\nexport function createCodingPack(options: ICodingPackOptions): ICapabilityPack {\n  const toolOptions = {\n    cwd: options.cwd,\n    httpUserAgent: options.httpUserAgent,\n    ...(options.shellExecutable !== undefined ? { shellExecutable: options.shellExecutable } : {}),\n    ...(options.sandboxClient ? { sandboxClient: options.sandboxClient } : {}),\n    ...(options.editorFiles ? { editorFiles: options.editorFiles } : {}),\n  };\n\n  return {\n    id: 'coding',\n    title: 'Coding',\n    description:\n      \"Built-in coding capability: file/shell tools, /shell + /editor + /git commands, and the coding subagents.\",\n    // ARCH-035: the always-present default set, consumed from its owner rather than rebuilt here.\n    //\n    // This list used to be hand-maintained, identical to `createDefaultTools()`'s always-present\n    // tier, and the two were held together by a test asserting their NAMES matched. That pin is what\n    // let ARCH-021's first TC-05 pass without being able to fail: comparing tool names cannot tell a\n    // pack-composed surface from an imported-default one when the pack is pinned to the defaults.\n    // Consuming the set makes the relationship structural, so there is nothing left to drift.\n    //\n    // The adapter-gated tools stay out, as before: `createDefaultTools` adds `CodebaseRetrieval` only\n    // when given a `retrievalAdapter` and the Computer tools only when given a `computerDriver`, and\n    // this pack supplies neither. SEC-007 still holds — `cwd` is REQUIRED here, so the file-tool\n    // guard cannot be disarmed by omission, and the leaf threads it into every tool it builds.\n    tools: createDefaultTools(toolOptions),\n    commandModules: [\n      createShellCommandModule(options.shellExecutable),\n      createEditorCommandModule(options.editorTemporaryDirectoryPrefix),\n      createGitCommandModule(),\n    ],\n    subagents: BUILT_IN_AGENTS,\n  };\n}\n"],"mappings":"mQA+EA,SAAgB,EAAiB,EAA8C,CAS7E,MAAO,CACL,GAAI,SACJ,MAAO,SACP,YACE,4GAaF,MAAO,EAAmB,CAxB1B,IAAK,EAAQ,IACb,cAAe,EAAQ,cACvB,GAAI,EAAQ,kBAAoB,IAAA,GAA2D,CAAC,EAAhD,CAAE,gBAAiB,EAAQ,eAAgB,EACvF,GAAI,EAAQ,cAAgB,CAAE,cAAe,EAAQ,aAAc,EAAI,CAAC,EACxE,GAAI,EAAQ,YAAc,CAAE,YAAa,EAAQ,WAAY,EAAI,CAAC,CAoB9B,CAAC,EACrC,eAAgB,CACd,EAAyB,EAAQ,eAAe,EAChD,EAA0B,EAAQ,8BAA8B,EAChE,EAAuB,CACzB,EACA,UAAW,CACb,CACF"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@robota-sdk/pack-coding",
+  "version": "3.0.0-beta.100",
+  "description": "Robota's coding capability pack — an ICapabilityPack bundling the built-in coding tools, coding command modules, and coding subagents",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "node": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      },
+      "default": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@robota-sdk/agent-command": "3.0.0-beta.100",
+    "@robota-sdk/agent-framework": "3.0.0-beta.100",
+    "@robota-sdk/agent-capability-pack": "3.0.0-beta.100",
+    "@robota-sdk/agent-tool-defaults": "3.0.0-beta.100",
+    "@robota-sdk/agent-tools": "3.0.0-beta.100"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.10",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.6"
+  },
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "publishConfig": {
+    "access": "public"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota"
+  },
+  "bugs": {
+    "url": "https://github.com/woojubb/robota/issues"
+  },
+  "homepage": "https://robota.io/",
+  "scripts": {
+    "build": "rimraf dist && tsdown",
+    "build:js": "pnpm run build",
+    "build:types": "pnpm run build",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "typecheck": "tsgo --noEmit",
+    "lint": "eslint src/ --ext .ts",
+    "clean": "rimraf dist"
+  }
+}