@cspeach/cli 1.1.18 → 1.1.20

package/dist/tools/tool-loading.js

@@ -0,0 +1,255 @@
+import { toAnthropicTools } from './index.js';
+/** The server-side tool search tool (probe P6: this exact name). */
+export const TOOL_SEARCH_TOOL = Object.freeze({
+    type: 'tool_search_tool_regex_20251119',
+    name: 'tool_search_tool_regex',
+});
+/** Beta that allows `role: 'system'` tool_addition messages (and rides with deferred tools). */
+export const TOOL_CHANGES_BETA = 'mid-conversation-tool-changes-2026-07-01';
+/**
+ * Spec D11 — always loaded. Names missing from the list a build is given
+ * (flag-gated `agent_run` / file tools when their flag is off; every SAP tool
+ * in standalone) are skipped, never an error (ruling F25). `read_agent`
+ * (Task 18) is core because the preamble's heavy-reading rule names it.
+ */
+export const CORE_TOOLS = Object.freeze([
+    'ask_question',
+    'todo_set',
+    'request_approval',
+    'dispatch_skill',
+    'agent_run',
+    'read_agent',
+    'file_read',
+    'tool_output_read',
+    'file_write',
+    'shell_exec',
+    'sap_get_source',
+    'sap_search_object',
+    'sap_object_structure',
+    'sap_sql_query',
+    'sap_syntax_check',
+    'sap_set_source',
+    'sap_update_method',
+    'sap_activate',
+    'sap_inactive_objects',
+    'sap_create_object',
+]);
+const FIORI_FAMILY = [
+    'fiori_apply', 'fiori_deploy_config', 'fiori_draft_smoke', 'fiori_fe_extend',
+    'fiori_list', 'fiori_metadata_audit', 'fiori_preview', 'fiori_render_smoke',
+    'fiori_sample_get', 'fiori_sample_search', 'fiori_scaffold', 'fiori_scaffold_fe',
+];
+const TRANSPORT_FAMILY = [
+    'sap_transport_create', 'sap_transport_for_object', 'sap_transport_list', 'sap_transport_release',
+];
+/**
+ * Per-skill starter tools: the non-core tools a skill's body names as its
+ * working set (counted from `.claude/skills/<skill>/SKILL.md`). A tool left
+ * out is still reachable through tool search — a starter only saves the
+ * search round. Skills not listed start with the core set alone.
+ */
+export const SKILL_STARTERS = Object.freeze({
+    'abap-fiori-build': FIORI_FAMILY,
+    'abap-transport': TRANSPORT_FAMILY,
+    'abap-transport-analysis': [...TRANSPORT_FAMILY, 'sap_atc_run', 'sap_usage_references'],
+    'abap-cap': ['fiori_scaffold_fe', 'fiori_render_smoke', 'fiori_draft_smoke'],
+    'abap-atc-fix': ['sap_atc_run'],
+    'abap-cca': ['sap_atc_run', 'sap_usage_references', 'sap_api_state'],
+    'abap-clean-core': ['sap_api_state', 'sap_atc_run', 'sap_usage_references'],
+    'abap-data-model': ['sap_create_domain', 'sap_create_data_element'],
+    'abap-document': ['sap_usage_references'],
+    'abap-handover': ['sap_usage_references'],
+    'abap-impact': ['sap_usage_references', 'sap_atc_run'],
+    'abap-performance': ['sap_usage_references', 'sap_atc_run'],
+    'abap-migrate': ['sap_usage_references'],
+    'abap-dump': ['sap_short_dump', 'sap_snapshot_take'],
+    'abap-incident': ['sap_short_dump', 'sap_snapshot_take', 'sap_atc_run', 'sap_run_unit_test', 'sap_api_state', 'sap_diff'],
+    'abap-eml': ['sap_run_unit_test'],
+    'abap-test': ['sap_run_unit_test', 'sap_set_class_include'],
+    'abap-extend-model': ['extend_model_insert', 'sap_snapshot_take', 'sap_service_binding_publish', 'sap_set_class_include'],
+    'abap-rap': ['sap_set_class_include', 'sap_service_binding_publish', 'sap_class_includes'],
+    'abap-modernize': ['sap_api_state', 'sap_snapshot_take', 'sap_service_binding_publish', 'sap_atc_run', 'sap_transport_create'],
+    'abap-segw': ['sap_snapshot_take', 'sap_odata_test'],
+    'abap-upgrade-fix': ['sap_snapshot_take', 'glob'],
+    'abap-upgrade-scan': ['sap_atc_run'],
+    'abap-upgrade-verify': ['sap_atc_run'],
+});
+/** The starter tools for a skill; unknown skill (or none) ⇒ []. */
+export function startersForSkill(skill) {
+    if (!skill)
+        return [];
+    const s = SKILL_STARTERS[skill];
+    return s ? [...s] : [];
+}
+/**
+ * Final review C1 (controller ruling, 2026-09-28) — ALLOW-list of the model
+ * families the deferred shapes (defer_loading entries, the tool search tool,
+ * `role: 'system'` tool_addition messages) were probe-proven on (P6, D1, D3:
+ * claude-opus-5 and claude-opus-5-5). Same matching as the other allow-lists
+ * in agent/provider-shape.ts (lowercased, trailing -YYYYMMDD stripped). Every
+ * other model — claude-opus-4-8 (the session default until the global flip),
+ * the claude-sonnet-4-6 plan/audit tier, haiku — gets the static list. The
+ * loop decides by the model actually sent on each call.
+ */
+export const DEFERRED_TOOL_MODELS = new Set([
+    'claude-opus-5-5', 'claude-opus-5',
+]);
+export function modelAcceptsDeferredTools(model) {
+    if (typeof model !== 'string')
+        return false;
+    return DEFERRED_TOOL_MODELS.has(model.trim().toLowerCase().replace(/-\d{8}$/, ''));
+}
+/**
+ * Mode precedence (ruling F13): AI-hub and local are always 'static' (their
+ * wire has no deferred loading). Otherwise env `CSPEACH_TOOL_LOADING`
+ * (`deferred` | `static`) wins; then managed uses the served value (default
+ * 'static': only a proxy that serves tool_loading takes the new shapes);
+ * BYOK uses the served value when it fetched one, else 'static'.
+ */
+export function resolveToolLoading(i) {
+    if (i.providerMode === 'ai-hub' || i.providerMode === 'local')
+        return 'static';
+    const raw = i.env.CSPEACH_TOOL_LOADING?.trim().toLowerCase();
+    if (raw === 'deferred' || raw === 'static')
+        return raw;
+    // Task 21 fix round (controller ruling): an old proxy serves no tool_loading
+    // and adds none of the deferred-tool betas, so 'deferred' only when served.
+    if (i.providerMode === 'managed')
+        return i.served ?? 'static';
+    if (i.providerMode === 'byok')
+        return i.served ?? 'static';
+    // Unknown/fake provider modes keep today's full list.
+    return 'static';
+}
+/**
+ * Build the `tools[]` array. 'static' ⇒ exactly today's list
+ * (toAnthropicTools). 'deferred' ⇒ loaded entries (core ∪ starters, in
+ * registry order, byte-identical to today's entries), then every other tool
+ * with `defer_loading: true` (registry order), then the tool search tool —
+ * the search tool only when at least one entry is deferred.
+ */
+export function buildToolList(tools, opts) {
+    if (opts.mode === 'static')
+        return toAnthropicTools(tools);
+    const loadedNames = new Set([...CORE_TOOLS, ...startersForSkill(opts.skill)]);
+    const loaded = tools.filter((t) => loadedNames.has(t.name));
+    const deferred = tools.filter((t) => !loadedNames.has(t.name));
+    // Final review I1 — nothing deferred ⇒ nothing to search: no search tool
+    // (plan audit's `toolFilter: () => false` means "no tools at all" ⇒ []).
+    if (deferred.length === 0)
+        return toAnthropicTools(loaded);
+    return [
+        ...toAnthropicTools(loaded),
+        ...toAnthropicTools(deferred).map((t) => ({ ...t, defer_loading: true })),
+        { ...TOOL_SEARCH_TOOL },
+    ];
+}
+/** Names of the entries a built list declares with `defer_loading: true`. */
+export function deferredNames(toolList) {
+    const out = new Set();
+    for (const t of toolList) {
+        if (t && t.defer_loading === true && typeof t.name === 'string')
+            out.add(t.name);
+    }
+    return out;
+}
+/** True for the tool search entry of a built list (the one predicate; provider-shape re-exports it). */
+export function isToolSearchEntry(t) {
+    return !!t && typeof t === 'object' && t.type === TOOL_SEARCH_TOOL.type;
+}
+/**
+ * Probe D2 (2026-09-27): the API rejects a `role: 'system'` message followed
+ * by a user message — "role 'system' must precede an 'assistant' message or
+ * end the array" (400). A tool_addition pushed after a tool-result message
+ * can be followed by a user message when the next round adds one first (mid-
+ * turn steering, the watchdog nudge) or when the turn ended before the model
+ * answered (refusal, interruption) and the next turn's prompt is pushed, and
+ * a later skill switch can then append a second tool_addition.
+ *
+ * Only the TAIL after the last assistant message is ever touched (the whole
+ * array when there is none): it holds only user and system messages, none of
+ * which an assistant message has followed yet, so no thinking block's prefix
+ * changes (at most the uncached tail is re-written). The tail is stably
+ * partitioned: user messages first (in order), then the system messages'
+ * blocks (in order) merged into ONE system message that ends the array — the
+ * shape probe D3 proved, its next round included. Merging avoids a
+ * [system, system] run, whose acceptance was never probed; one system message
+ * with several tool_addition blocks is the shape the CLI already sends for a
+ * skill's starters. Anything before the last assistant message is left
+ * exactly as it is. Mutates `messages`; returns the number of system messages
+ * moved or merged. Idempotent: a second pass is a no-op.
+ */
+export function placeSystemMessagesInPlace(messages) {
+    if (!messages)
+        return 0;
+    let tailStart = messages.length;
+    while (tailStart > 0 && messages[tailStart - 1]?.role !== 'assistant')
+        tailStart--;
+    const tail = messages.slice(tailStart);
+    const users = tail.filter((m) => m?.role !== 'system');
+    const systems = tail.filter((m) => m?.role === 'system');
+    if (systems.length === 0)
+        return 0;
+    // Already in shape: users, then exactly one system message last.
+    if (systems.length === 1 && tail[tail.length - 1] === systems[0])
+        return 0;
+    const merged = {
+        role: 'system',
+        content: systems.flatMap((m) => (Array.isArray(m.content) ? m.content : [])),
+    };
+    messages.splice(tailStart, tail.length, ...users, merged);
+    return systems.length;
+}
+/**
+ * A `role: 'system'` message surfacing deferred tools by reference. Names not
+ * in `deferredSet` (loaded already, or unknown in this build) are dropped;
+ * nothing left ⇒ null.
+ */
+export function buildToolAdditionMessage(names, deferredSet) {
+    const keep = [...new Set(names)].filter((n) => deferredSet.has(n));
+    if (keep.length === 0)
+        return null;
+    return {
+        role: 'system',
+        content: keep.map((name) => ({ type: 'tool_addition', tool: { type: 'tool_reference', name } })),
+    };
+}
+/**
+ * Integration finding N1 (c) — the tool_addition for a skill switch: the
+ * skill's starters that the CURRENT mode's list (`toolList`, the list the
+ * next request carries) declares deferred, minus those the conversation has
+ * already surfaced. A session pinned 'static' never gets one, whatever list
+ * the caller holds (a static request cannot carry a `role: 'system'`
+ * tool_addition). Nothing to add ⇒ null.
+ */
+export function buildSkillToolAddition(i) {
+    if (i.toolLoading === 'static')
+        return null;
+    const surfaced = surfacedToolNames(i.messages);
+    return buildToolAdditionMessage(startersForSkill(i.skill).filter((n) => !surfaced.has(n)), deferredNames(i.toolList));
+}
+/**
+ * Tool names already surfaced in a conversation: every `tool_addition`
+ * reference (`tool.name`) and every search-result reference (`tool_name`).
+ * Used so a skill switch never re-adds a tool.
+ */
+export function surfacedToolNames(messages) {
+    const out = new Set();
+    for (const m of messages ?? []) {
+        if (!Array.isArray(m?.content))
+            continue;
+        for (const b of m.content) {
+            if (b?.type === 'tool_addition' && typeof b.tool?.name === 'string')
+                out.add(b.tool.name);
+            if (b?.type === 'tool_search_tool_result') {
+                const refs = b.content?.tool_references;
+                if (Array.isArray(refs)) {
+                    for (const r of refs)
+                        if (typeof r?.tool_name === 'string')
+                            out.add(r.tool_name);
+                }
+            }
+        }
+    }
+    return out;
+}

package/dist/tools/tool-output-read.js

@@ -0,0 +1,117 @@
+/**
+ * tool_output_read — Task 17 ruling (2026-09-27).
+ *
+ * Large tool results are saved to ~/.cspeach/streams/<sessionId>/tool-<id>.txt
+ * (result-spill.ts) and the history keeps a preview naming this tool. It is
+ * always registered (not flag-gated — file_read is off in a plain SAP session),
+ * read-only, in CORE_TOOLS, and reads ONLY the current session's spill files
+ * (a reader child: also its parent session's — final review tools-I4): the
+ * path must be a tool-*.txt directly inside one of those spill dirs, and
+ * it is re-checked after realpath (a symlink cannot point it elsewhere).
+ * Anything else — including a ctx with no session id — is an error result.
+ * Its own result is never spilled; instead it has a char budget.
+ */
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import { registerTool } from './index.js';
+import { spillDirFor, sessionIdOf, SPILL_FILE_RE, NUMBERED_SPILL_RE, SPILL_MAX_AGE_DAYS, withRealpath, } from './result-spill.js';
+const MAX_LINES = 2000;
+/** Total characters one call returns (fix round 1, minor 2). */
+export const TOOL_OUTPUT_READ_MAX_CHARS = 40_000;
+/** One returned line never carries more than this. */
+export const TOOL_OUTPUT_READ_LINE_MAX_CHARS = 2_000;
+const REFUSED = 'not a saved tool output of this session';
+const err = (msg) => ({ content: `error: ${msg}`, is_error: true });
+/** Case-insensitive file systems (win32, darwin default) compare paths case-insensitively. */
+const norm = (p) => (process.platform === 'win32' || process.platform === 'darwin' ? p.toLowerCase() : p);
+/** The spill file itself must sit directly in one of the session-dir spellings. */
+function directlyIn(dirs, file) {
+    const parent = norm(path.dirname(file));
+    return dirs.some((d) => norm(d) === parent);
+}
+function clip(line) {
+    return line.length <= TOOL_OUTPUT_READ_LINE_MAX_CHARS
+        ? line
+        : `${line.slice(0, TOOL_OUTPUT_READ_LINE_MAX_CHARS)}… [+${line.length - TOOL_OUTPUT_READ_LINE_MAX_CHARS} chars]`;
+}
+export async function toolOutputReadHandler(args, ctx) {
+    const sessionId = sessionIdOf(ctx);
+    if (sessionId === undefined)
+        return err(REFUSED);
+    const p = typeof args.path === 'string' ? args.path : '';
+    if (p.length === 0 || p.includes('\0') || !path.isAbsolute(p)) {
+        return err('path must be the absolute spill-file path shown in the tool result');
+    }
+    const offset = args.offset === undefined ? 0 : Number(args.offset);
+    const limitArg = args.limit === undefined ? MAX_LINES : Number(args.limit);
+    if (!Number.isInteger(offset) || offset < 0)
+        return err(`offset must be a non-negative integer (got ${String(args.offset)})`);
+    if (!Number.isInteger(limitArg) || limitArg < 1)
+        return err(`limit must be a positive integer (got ${String(args.limit)})`);
+    const limit = Math.min(limitArg, MAX_LINES);
+    // Final review tools-I4 — a reader child may also read its parent's saved
+    // outputs: that one dir only, and only on a reader ctx.
+    const parentId = ctx.readerMode && typeof ctx.spillParentSessionId === 'string' && ctx.spillParentSessionId.length > 0
+        ? ctx.spillParentSessionId
+        : undefined;
+    const dirs = [
+        ...withRealpath(spillDirFor(sessionId)),
+        ...(parentId !== undefined ? withRealpath(spillDirFor(parentId)) : []),
+    ];
+    const abs = path.resolve(p);
+    if (!SPILL_FILE_RE.test(path.basename(abs)) || !directlyIn(dirs, abs))
+        return err(REFUSED);
+    let real;
+    try {
+        real = await fsp.realpath(abs);
+    }
+    catch (e) {
+        return err(e.code === 'ENOENT'
+            ? `saved output not found (saved outputs are kept ${SPILL_MAX_AGE_DAYS} days)`
+            : 'cannot read saved output');
+    }
+    if (!SPILL_FILE_RE.test(path.basename(real)) || !directlyIn(dirs, real))
+        return err(REFUSED);
+    let raw;
+    try {
+        raw = await fsp.readFile(real, 'utf-8');
+    }
+    catch {
+        return err('cannot read saved output');
+    }
+    // A `.n.txt` spill (file_read) already carries the file's line numbers.
+    const numberedAlready = NUMBERED_SPILL_RE.test(real);
+    const all = raw.replace(/\n$/, '').split('\n');
+    const end = Math.min(all.length, offset + limit);
+    const out = [];
+    let used = 0;
+    let next = offset;
+    for (let i = offset; i < end; i++) {
+        const line = clip(numberedAlready ? all[i] : `${i + 1}\t${all[i]}`);
+        if (out.length > 0 && used + line.length + 1 > TOOL_OUTPUT_READ_MAX_CHARS)
+            break;
+        out.push(line);
+        used += line.length + 1;
+        next = i + 1;
+    }
+    const rest = all.length - next;
+    return { content: out.join('\n') + (rest > 0 ? `\n... (${rest} more lines — next offset=${next})` : '') };
+}
+registerTool({
+    name: 'tool_output_read',
+    description: 'Read a slice of a large tool result that was saved to a file (the result names the path). '
+        + 'Returns numbered lines. offset is 0-based; limit defaults to and caps at 2000 lines (40 000 chars). '
+        + 'Only this session\'s saved outputs can be read.',
+    isMutating: false,
+    category: 'filesystem',
+    input_schema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'The saved-output path from the tool result.' },
+            offset: { type: 'number', description: 'Optional 0-based line offset.' },
+            limit: { type: 'number', description: 'Optional max lines (cap 2000).' },
+        },
+        required: ['path'],
+    },
+    handler: toolOutputReadHandler,
+});