@robota-sdk/agent-tool-defaults 3.0.0-beta.100

package/src/create-default-tools.ts

@@ -0,0 +1,124 @@
+/**
+ * The DEFAULT TOOL SET — a composition leaf.
+ *
+ * ARCH-035 moved this out of `@robota-sdk/agent-framework`. It is a defaults aggregator, and
+ * `.agents/project-structure.md` classifies that family as a composition leaf "imported only at
+ * composition roots (entry-point-only)" — not something a mid-layer assembly library owns, publishes
+ * and self-consumes.
+ *
+ * The move is what carries the guarantee. `agent-subagent-runner` may depend on `agent-framework`
+ * (it needs `createSubagentSession` and friends) but has no manifest edge to THIS package, so
+ * `import { createDefaultTools } from '@robota-sdk/agent-tool-defaults'` does not resolve there at
+ * all. A neutral runner composing the product's tool surface is now a compile error rather than a
+ * scan finding — the same shape ARCH-021 achieved on the provider axis with
+ * `@robota-sdk/agent-builtin-providers`.
+ *
+ * `DEFAULT_TOOL_DESCRIPTIONS` deliberately did NOT come along: its only consumer builds the system
+ * prompt synchronously, and dragging it here would force either a static edge back into this leaf or
+ * a second async hop through prompt building. It stays beside its consumer in `agent-framework`.
+ */
+import {
+  createAskUserQuestionTool,
+  createShellTool,
+  createBashTool,
+  createReadTool,
+  createWriteTool,
+  createEditTool,
+  createRetrievalTool,
+  createComputerTool,
+  createGlobTool,
+  createGrepTool,
+  createWebFetchTool,
+  createWebSearchTool,
+  routesFilesThroughSandbox,
+} from '@robota-sdk/agent-tools';
+
+import type { FunctionTool } from '@robota-sdk/agent-core';
+import type {
+  IComputerDriver,
+  IEditorFileAccess,
+  IRetrievalAdapter,
+  ISandboxClient,
+} from '@robota-sdk/agent-tools';
+
+/**
+ * Create the default set of CLI tools.
+ * Returns the standard tools.
+ */
+export interface ICreateDefaultToolsOptions {
+  sandboxClient?: ISandboxClient;
+  /** Host-selected executable for Shell and Bash. */
+  shellExecutable?: string;
+  httpUserAgent?: string;
+  /**
+   * The execution root every file tool is contained by. REQUIRED — ARCH-010.
+   *
+   * It was optional, and `child-process-subagent-worker.ts` called this factory with no argument at
+   * all: `cwd` was `undefined`, the path guard was fail-open, and the subagent's `Read` returned
+   * `/etc/hostname`. Requiring it means a construction site that forgets does not compile, which is
+   * the only way a containment root stays a contract rather than a convention.
+   */
+  cwd: string;
+  /**
+   * An editor that has the workspace open, asked at each call. The host file tools read and write
+   * through what it offers and the searches say they read the disk; commands never use it, and a
+   * sandbox with its own filesystem keeps every file tool, since its files are not the editor's.
+   */
+  editorFiles?: () => IEditorFileAccess | undefined;
+  /** SELFHOST-003: when present, adds the adapter-gated `CodebaseRetrieval` tool (absent otherwise). */
+  retrievalAdapter?: IRetrievalAdapter;
+  /**
+   * SELFHOST-010: when present, adds the adapter-gated `ComputerView` + `Computer` tools. Unlike the
+   * shell tool's host `spawn` fallback, computer-use has NO host fallback — with no driver the tools are
+   * simply ABSENT (there is no safe library-side "local" screen to fall back to).
+   */
+  computerDriver?: IComputerDriver;
+}
+
+/**
+ * ARCH-035: returns `FunctionTool[]`, which is what every factory below actually returns.
+ *
+ * An earlier revision cast each one to `IToolWithEventService` because session assembly consumes that
+ * interface. The cast was lossy in the direction that mattered: `ICapabilityPack.tools` is
+ * `readonly FunctionTool[]`, so a pack CONSUMING this set could not assign it without a second cast
+ * back — one erasure creating the need for another. `FunctionTool` satisfies `IToolWithEventService`,
+ * so session assembly is unaffected and no cast is needed at either end.
+ */
+export function createDefaultTools(options: ICreateDefaultToolsOptions): FunctionTool[] {
+  // Issue #3081: the sandbox's filesystem relation decides where file tools read and write. On a
+  // SEPARATE filesystem every file tool goes through the sandbox — and `Glob`/`Grep`, which have no
+  // sandbox path, are withheld, so a search can never read the host while an edit writes the
+  // sandbox. On a SHARED filesystem (commands confined over the host's) file tools stay on the host
+  // under the path guard, and only commands run through the sandbox.
+  const separate = routesFilesThroughSandbox(options.sandboxClient);
+  // An editor holds the host's files, so it reaches only the tools that work on them; commands keep
+  // the agent's own sandbox.
+  const { editorFiles: _hostFilesOnly, ...commandOptions } = options;
+  const { sandboxClient: _commandsOnly, ...hostFileOptions } = options;
+  const fileOptions = separate ? commandOptions : hostFileOptions;
+  return [
+    createShellTool(commandOptions),
+    createBashTool(commandOptions),
+    createReadTool(fileOptions),
+    createWriteTool(fileOptions),
+    createEditTool(fileOptions),
+    // SEC-007: built per call, NOT the module-level singletons. A singleton is context-free by
+    // construction, so registering one meant `Glob`/`Grep` could enumerate outside the session's
+    // working directory while `Read`/`Write`/`Edit` were contained.
+    ...(separate ? [] : [createGlobTool(hostFileOptions), createGrepTool(hostFileOptions)]),
+    // MUST 4: also built per call, for the same reason — `webFetchTool`/`webSearchTool` are
+    // module-level singletons in `agent-tools`, so two concurrently open sessions built from this
+    // set (e.g. two `sessionParticipant`s) shared them and tripped `resource-reused` even though
+    // nothing about a WebFetch/WebSearch tool actually needs to be shared across sessions.
+    createWebFetchTool({ userAgent: options.httpUserAgent }),
+    createWebSearchTool(),
+    createAskUserQuestionTool(),
+    // Retrieval is adapter-gated: absent when no adapter is supplied (there is no host fallback).
+    ...(options.retrievalAdapter
+      ? [createRetrievalTool({ adapter: options.retrievalAdapter })]
+      : []),
+    // Computer-use is adapter-gated on the driver: absent when no driver is supplied. There is NO host
+    // fallback (unlike the shell tool's host spawn) — no library-side "local" screen exists.
+    ...(options.computerDriver ? createComputerTool({ driver: options.computerDriver }) : []),
+  ];
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * `@robota-sdk/agent-tool-defaults` — the SDK's built-in default tool set, as a composition leaf.
+ *
+ * WHOSE defaults (#2202): the agent runtime SDK's own — the tools every product session gets unless the
+ * composition root supplies its own list. It composes ONE lower-layer package (`agent-tools`); it does
+ * not bundle same-level `agent-tool-*` siblings, so it is not an aggregator in the STRUCT-011 sense
+ * and keeps its name. Only the description had to say whose.
+ *
+ * Import this at a composition root. It is deliberately NOT re-exported by
+ * `@robota-sdk/agent-framework`: a pass-through re-export would restore the very route ARCH-035
+ * closed, and STRUCT-07 bans it independently.
+ */
+export { createDefaultTools } from './create-default-tools.js';
+export type { ICreateDefaultToolsOptions } from './create-default-tools.js';