@yolk-sdk/codemode 0.1.0-canary.106 → 0.1.0-canary.108

package/src/node.ts

@@ -121,7 +121,7 @@ const maxArgumentDepth = 64
  * proxy (close-match suggestions). Not a security boundary (`globalThis.tools` is unguarded):
  * arguments are still decoded by the host.
  */
-const toolsGuardSource = `(function (tools, labels) {
+const toolsGuardSource = `(function (tools, labels, unbound) {
   // Captured before the script runs, so a script that changes built-ins cannot change the checks.
   const { apply, getPrototypeOf, setPrototypeOf } = Reflect
   const isFinite = Number.isFinite
@@ -259,8 +259,13 @@ const toolsGuardSource = `(function (tools, labels) {
     if (!wrappers.has(call)) wrappers.set(call, wrap('tools[' + JSON.stringify(key) + ']', call))
     guarded[key] = wrappers.get(call)
   }
+  // Unbound keys (stage-only tools) reject with their hint instead of being undefined.
+  const rejections = create(null)
+  for (const [key, message] of unbound) {
+    if (!(key in guarded)) rejections[key] = async () => { throw new TypeErrorCtor(message) }
+  }
   return new Proxy(Object.freeze(guarded), {
-    get: (target, key) => (key in target ? target[key] : tools[key])
+    get: (target, key) => (key in target ? target[key] : key in rejections ? rejections[key] : tools[key])
   })
 })`
 
@@ -275,7 +280,10 @@ const jsonSource = (value: unknown) =>
     char === '\u2028' ? '\\u2028' : '\\u2029'
   )
 
-const guardSuffix = (tools: ReadonlyArray<CodeModeExecutorTool>) => {
+const guardSuffix = (
+  tools: ReadonlyArray<CodeModeExecutorTool>,
+  unbound: CodeModeExecuteOptions['unbound']
+) => {
   const names = tools.map(tool => tool.name)
   const labels = codeModeCallLabels(names)
 
@@ -285,7 +293,9 @@ const guardSuffix = (tools: ReadonlyArray<CodeModeExecutorTool>) => {
     tool.callLabel ?? labels[index] ?? `tools[${JSON.stringify(tool.name)}]`
   ])
 
-  return `\n})(${toolsGuardSource}(tools, ${jsonSource(pairs)}), console)`
+  const rejected = (unbound ?? []).map(entry => [entry.key, entry.message])
+
+  return `\n})(${toolsGuardSource}(tools, ${jsonSource(pairs)}, ${jsonSource(rejected)}), console)`
 }
 
 const lineTerminators = /\r\n?|[\n\u2028\u2029]/g
@@ -510,11 +520,14 @@ export const makePiCodeModeExecutor = (
 
     try {
       return fromPiResult(
-        await sandbox.execute(`${guardPrefix}${stripped.code}${guardSuffix(execution.tools)}`, {
-          signal: execution.signal,
-          store: execution.store,
-          timeoutMs
-        }),
+        await sandbox.execute(
+          `${guardPrefix}${stripped.code}${guardSuffix(execution.tools, execution.unbound)}`,
+          {
+            signal: execution.signal,
+            store: execution.store,
+            timeoutMs
+          }
+        ),
         scriptLineCount(stripped.code)
       )
     } finally {

package/src/search.ts

@@ -1,113 +1,59 @@
+import { rankToolSearchDocuments, toolSearchTokens } from '@yolk-sdk/agent/tools'
 import type { CodeModeCatalogTool } from './catalog.ts'
 
 /** Default number of `searchTools` results. */
 export const defaultCodeModeSearchLimit = 8
 
-const k1 = 1.2
-
-const b = 0.75
-
-/** Lowercase word tokens; splits on non-alphanumerics and camelCase boundaries. */
-export const codeModeSearchTokens = (text: string): ReadonlyArray<string> =>
-  text
-    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-    .toLowerCase()
-    .split(/[^a-z0-9]+/)
-    .filter(token => token.length > 0)
-
-type IndexedTool = {
-  readonly tool: CodeModeCatalogTool
-  readonly frequencies: ReadonlyMap<string, number>
-  readonly length: number
-}
-
-const indexTool = (tool: CodeModeCatalogTool): IndexedTool => {
-  const tokens = codeModeSearchTokens(
-    [
-      tool.identifier,
-      tool.name,
-      tool.description,
-      tool.namespace,
-      tool.namespaceDescription ?? ''
-    ].join(' ')
-  )
-
-  const frequencies = new Map<string, number>()
-
-  for (const token of tokens) {
-    frequencies.set(token, (frequencies.get(token) ?? 0) + 1)
-  }
-
-  return { tool, frequencies, length: tokens.length }
-}
-
 export type CodeModeSearchOptions = {
   readonly limit?: number
   readonly namespace?: string
 }
 
 export type CodeModeSearchHit = {
-  /** The identifier scripts call as `tools.<name>(args)`. */
+  /** The identifier scripts call as `tools.<name>(args)`, or for a stage-only tool the name
+   * scripts pass to `stage(name, args)`.
+   */
   readonly name: string
   readonly description: string
+  /** A stage-only tool (ADR 0007): no `tools` binding, only `stage()` it. */
+  readonly stageOnly?: true
 }
 
 /**
- * BM25 over each tool's identifier, raw name, description, namespace, and namespace description. Ties keep catalog order.
- * A query without words lists the (namespace-filtered) tools in catalog order.
+ * BM25 (the shared `rankToolSearchDocuments`) over each tool's identifier, raw name, description,
+ * namespace, and namespace description. Ties keep catalog order. A query without words lists the
+ * (namespace-filtered) tools in catalog order.
  */
 export const searchCodeModeTools = (
   catalog: ReadonlyArray<CodeModeCatalogTool>,
   query: string,
   options: CodeModeSearchOptions = {}
 ): ReadonlyArray<CodeModeSearchHit> => {
-  const limit = Math.max(0, Math.floor(options.limit ?? defaultCodeModeSearchLimit))
-
   const scoped =
     options.namespace === undefined
       ? catalog
       : catalog.filter(tool => tool.namespace === options.namespace)
 
-  const documents = scoped.map(indexTool)
-  const terms = [...new Set(codeModeSearchTokens(query))]
-
-  const hit = (tool: CodeModeCatalogTool): CodeModeSearchHit => ({
-    name: tool.identifier,
-    description: tool.description
-  })
-
-  if (terms.length === 0) {
-    return documents.slice(0, limit).map(document => hit(document.tool))
-  }
-
-  const averageLength =
-    documents.reduce((total, document) => total + document.length, 0) /
-    Math.max(1, documents.length)
-
-  const inverse = new Map(
-    terms.map((term): readonly [string, number] => {
-      const containing = documents.filter(document => document.frequencies.has(term)).length
-
-      return [term, Math.log(1 + (documents.length - containing + 0.5) / (containing + 0.5))]
-    })
-  )
-
-  return documents
-    .map((document, index) => {
-      const score = terms.reduce((total, term) => {
-        const frequency = document.frequencies.get(term) ?? 0
-
-        if (frequency === 0) return total
-
-        const norm = k1 * (1 - b + (b * document.length) / Math.max(1, averageLength))
-
-        return total + ((inverse.get(term) ?? 0) * frequency * (k1 + 1)) / (frequency + norm)
-      }, 0)
-
-      return { document, index, score }
-    })
-    .filter(entry => entry.score > 0)
-    .sort((left, right) => right.score - left.score || left.index - right.index)
-    .slice(0, limit)
-    .map(entry => hit(entry.document.tool))
+  const hit = (tool: CodeModeCatalogTool): CodeModeSearchHit =>
+    tool.exposure === 'stage'
+      ? { name: tool.name, description: tool.description, stageOnly: true }
+      : { name: tool.identifier, description: tool.description }
+
+  return rankToolSearchDocuments(
+    scoped.map(tool => ({
+      value: tool,
+      text: [
+        tool.identifier,
+        tool.name,
+        tool.description,
+        tool.namespace,
+        tool.namespaceDescription ?? ''
+      ].join(' ')
+    })),
+    query,
+    options.limit ?? defaultCodeModeSearchLimit
+  ).map(hit)
 }
+
+/** Lowercase word tokens of code mode search (the shared `toolSearchTokens`). */
+export const codeModeSearchTokens = toolSearchTokens

package/src/tool.ts

@@ -30,9 +30,12 @@ import {
   type NestedToolCallInput,
   type NestedToolCallStatus
 } from '@yolk-sdk/agent/protocol'
+import { toCodemodeIdentifier } from '@earendil-works/pi-codemode/declarations'
 import {
   makeTool,
+  type NestedTool,
   type NestedToolExecutor,
+  type NestedToolInstructor,
   type StagedCallReceipt,
   type ToolExecutionInput,
   type ToolLedgerAbandonedInput,
@@ -43,11 +46,15 @@ import {
 } from '@yolk-sdk/agent/tools'
 import {
   codeModeCatalog,
+  codeModeCatalogInstruction,
+  codeModeStageOnlyCatalog,
   defaultCodeModeInlineBudget,
   describeCodeModeTool,
   findCodeModeTool,
   renderCodeModeDescription,
-  type CodeModeCatalogTool
+  renderCodeModeInstructedDescription,
+  type CodeModeCatalogTool,
+  type CodeModeStagingDescription
 } from './catalog.ts'
 import type {
   CodeModeExecutionResult,
@@ -156,6 +163,15 @@ export type MakeCodeModeToolOptions<Context> = {
    * resolution's cap.
    */
   readonly staging?: CodeModeStagingOptions | false
+  /**
+   * Where the nested tool catalog goes (ADR 0007). `description` (default): in this tool's
+   * description, which changes with the catalog. `instructions`: the description stays invariant
+   * and the catalog (every namespace with its tool count, listed tools within `inlineBudget`) is
+   * the resolution's `instructions` entry; hosts pass `ResolvedToolSet.instructions` to
+   * `RunConfig.instructions`, so a change is appended to the conversation instead of rewriting the
+   * cached request prefix.
+   */
+  readonly catalog?: 'description' | 'instructions'
 }
 
 export type CodeModeStagingOptions = {
@@ -267,7 +283,11 @@ const hookOutcome = (exit: Exit.Exit<ToolResult>): CodeModeNestedCallOutcome =>
 type CodeModeNamespaceDescription = {
   readonly name: string
   description?: string
-  readonly tools: ReadonlyArray<{ readonly name: string; readonly description: string }>
+  readonly tools: ReadonlyArray<{
+    readonly name: string
+    readonly description: string
+    readonly stageOnly?: true
+  }>
 }
 
 const SearchOptions = Schema.Struct({
@@ -277,7 +297,8 @@ const SearchOptions = Schema.Struct({
 
 const decodeSearchOptions = Schema.decodeUnknownOption(SearchOptions)
 
-/** `searchTools`, `describeTool`, and `describeNamespace` over every nested tool. */
+/** `searchTools`, `describeTool`, and `describeNamespace` over every nested tool and, while the
+ * script may stage, every stage-only tool. */
 const discoveryGlobals = (
   catalog: ReadonlyArray<CodeModeCatalogTool>
 ): ReadonlyArray<CodeModeExecutorGlobal> => [
@@ -317,7 +338,11 @@ const discoveryGlobals = (
 
       const namespace: CodeModeNamespaceDescription = {
         name,
-        tools: tools.map(tool => ({ name: tool.identifier, description: tool.description }))
+        tools: tools.map(tool =>
+          tool.exposure === 'stage'
+            ? { name: tool.name, description: tool.description, stageOnly: true }
+            : { name: tool.identifier, description: tool.description }
+        )
       }
 
       if (description !== undefined) namespace.description = description
@@ -332,8 +357,15 @@ type StageFork = (
   options: { readonly signal: AbortSignal }
 ) => Fiber.Fiber<StagedCallReceipt, ToolPlanStageError>
 
-/** `stage(name, args)`: records one call into the script's plan (never runs it). */
-const stageGlobal = (plan: ToolPlanBuilder, fork: StageFork): CodeModeExecutorGlobal => ({
+/**
+ * `stage(name, args)`: records one call into the script's plan (never runs it). `name` is the raw
+ * tool name or its catalog identifier (what `searchTools` returns for callable tools).
+ */
+const stageGlobal = (
+  plan: ToolPlanBuilder,
+  fork: StageFork,
+  stageable: ReadonlyArray<NestedTool>
+): CodeModeExecutorGlobal => ({
   name: 'stage',
   spread: true,
   signature: '(name: string, args: object): Promise<{ staged: true; key: string; index: number }>',
@@ -347,8 +379,13 @@ const stageGlobal = (plan: ToolPlanBuilder, fork: StageFork): CodeModeExecutorGl
     if (!Predicate.isString(name))
       return Promise.reject(new Error('stage: the first argument must be a tool name.'))
 
+    const toolName =
+      stageable.find(({ def }) => def.name === name)?.def.name ??
+      stageable.find(({ def }) => toCodemodeIdentifier(def.name) === name)?.def.name ??
+      name
+
     return new Promise((resolve, reject) => {
-      fork(plan.stage({ name, params: params === undefined ? {} : params }), {
+      fork(plan.stage({ name: toolName, params: params === undefined ? {} : params }), {
         signal
       }).addObserver(exit => {
         if (Exit.isSuccess(exit)) {
@@ -373,6 +410,19 @@ const stageGlobal = (plan: ToolPlanBuilder, fork: StageFork): CodeModeExecutorGl
   }
 })
 
+/** A direct call of a stage-only tool rejects with a hint to stage it (ADR 0007). */
+const stageOnlyRejections = (stageOnly: ReadonlyArray<CodeModeCatalogTool>) =>
+  stageOnly.flatMap(tool => {
+    const message = `${tool.name} is approval-gated: record it with stage(${JSON.stringify(tool.name)}, args) instead of calling it.`
+
+    return tool.identifier === tool.name
+      ? [{ key: tool.name, message }]
+      : [
+          { key: tool.identifier, message },
+          { key: tool.name, message }
+        ]
+  })
+
 const planNotice = (plan: CodeModeStagedPlan) =>
   `\n\nStaged ${plan.count} call${plan.count === 1 ? '' : 's'} as plan ${plan.id}; nothing was applied yet. To apply them, call ${plan.reviewToolName}(${JSON.stringify({ planId: plan.id, planDigest: plan.digest })}): a person reviews the plan and selects the calls to apply.`
 
@@ -600,14 +650,23 @@ const runScript = <Context>(input: RunInput<Context>): Effect.Effect<ToolResult,
             execute: callTool(tool)
           }))
 
+          const stageOnly =
+            plan === undefined || staging === undefined
+              ? []
+              : codeModeStageOnlyCatalog(staging.tools)
+
           const result = yield* Effect.tryPromise({
             try: signal =>
               options.executor.execute(input.code, {
                 tools,
                 globals:
-                  plan === undefined
+                  plan === undefined || staging === undefined
                     ? discoveryGlobals(catalog)
-                    : [...discoveryGlobals(catalog), stageGlobal(plan, stageFork)],
+                    : [
+                        ...discoveryGlobals([...catalog, ...stageOnly]),
+                        stageGlobal(plan, stageFork, staging.tools)
+                      ],
+                unbound: stageOnlyRejections(stageOnly),
                 timeoutMs,
                 memoryLimitBytes: limits.memoryLimitBytes,
                 store,
@@ -893,18 +952,41 @@ export const makeCodeModeTool = <Context>(
   const inlineBudget = options.inlineBudget ?? defaultCodeModeInlineBudget
   const store = options.loadStore !== undefined
 
-  return makeTool<Context, typeof CodeModeParams>({
+  const instructed = options.catalog === 'instructions'
+
+  // In description mode `stage()` is documented once a stageable tool exists (the description
+  // lists them anyway). In instructions mode the description must not depend on tools: staging
+  // availability alone decides.
+  const offered = (staging: CodeModeStagingDescription | undefined) =>
+    options.staging === false ||
+    staging === undefined ||
+    (!instructed && staging.tools.length === 0)
+      ? undefined
+      : staging
+
+  const registration = makeTool<Context, typeof CodeModeParams>({
     name,
-    description: renderCodeModeDescription({ tools: [], inlineBudget, store }),
+    description: instructed
+      ? renderCodeModeInstructedDescription({ store })
+      : renderCodeModeDescription({ tools: [], inlineBudget, store }),
     parameters: CodeModeParams,
     access: 'write',
     nestedToolAccess: true,
-    describe: ({ tools, staging }) =>
-      renderCodeModeDescription(
-        staging === undefined || options.staging === false
+    describe: ({ tools, staging }) => {
+      const offeredStaging = offered(staging)
+
+      if (instructed)
+        return renderCodeModeInstructedDescription(
+          offeredStaging === undefined ? { store } : { store, staging: offeredStaging }
+        )
+
+      return renderCodeModeDescription(
+        offeredStaging === undefined
           ? { tools, inlineBudget, store }
-          : { tools, inlineBudget, store, staging }
-      ),
+          : { tools, inlineBudget, store, staging: offeredStaging }
+      )
+    },
+
     abandonedResult: abandonedScriptResult(limits),
     execute: ({
       call,
@@ -922,4 +1004,18 @@ export const makeCodeModeTool = <Context>(
           )
         : runScript({ options, limits, call, context, code: params.code, nested })
   })
+
+  if (!instructed) return registration
+
+  const instruct: NestedToolInstructor = ({ tools, staging }) => {
+    const offeredStaging = offered(staging)
+
+    return codeModeCatalogInstruction(
+      offeredStaging === undefined
+        ? { tools, inlineBudget }
+        : { tools, inlineBudget, staging: offeredStaging }
+    )
+  }
+
+  return { ...registration, instruct }
 }