@cspeach/cli 1.1.44 → 1.1.46

package/dist/tools/approval.js

@@ -1,4 +1,6 @@
 import chalk from 'chalk';
+import { notModifiableText } from './release-texts.js';
+import { isModifiable, knownObjectCount } from '@cspeach/sap-client';
 import { registerTool } from './index.js';
 import { isHeadless, shouldUseInk } from '../renderer/tty.js';
 import { effectiveRisk, riskReasonText, typeCode } from '../approvals/risk-floor.js';
@@ -120,6 +122,55 @@ function isPureInfraEscalation(changes) {
         changes.every((c) => c.op === 'create' &&
             INFRA_BASE_OBJECT_TYPES.has((c.type ?? '').trim().toUpperCase())));
 }
+/**
+ * Part 3 D12 — for every release change: drop any model-supplied facts, read
+ * the request from SAP and attach SAP's facts, or return the refusal. There is
+ * no separate "no SAP" branch: standalone's `ctx.adt` is a Proxy whose every
+ * method throws the standalone text, so the throw path IS the standalone path.
+ */
+async function attachReleaseFacts(changes, ctx) {
+    for (const c of changes) {
+        if (!c)
+            continue;
+        // Never the model's facts — on any change.
+        delete c.releaseFacts;
+        if (c.op !== 'release')
+            continue;
+        if (typeCode(c.type) !== 'CTS') {
+            return { error: 'release_type', message: 'A release change has type CTS and names the request number.' };
+        }
+        const asked = String(c.object ?? '').trim();
+        let doc;
+        try {
+            doc = await ctx.adt.transportRead(asked);
+        }
+        catch (e) {
+            const why = e instanceof Error ? e.message : String(e);
+            return {
+                error: 'release_facts_unavailable',
+                message: `CSPeach could not read ${asked}, so it cannot show what a release would send. (${why})`,
+            };
+        }
+        if (doc.kind === 'task') {
+            return {
+                error: 'task_number',
+                message: `${asked} is a task of ${doc.number}. Give the request number; CSPeach releases the tasks first, then the request.`,
+            };
+        }
+        if (!isModifiable(doc.status)) {
+            return { error: 'not_modifiable', message: notModifiableText(doc) };
+        }
+        c.releaseFacts = {
+            request: doc.number, description: doc.description, owner: doc.owner, target: doc.target,
+            status: doc.status, statusText: doc.statusText,
+            tasks: doc.tasks.map((t) => ({ number: t.number, owner: t.owner })),
+            // The largest count the document supports; null = could not count
+            // (the card says so, never "0 objects").
+            objects: knownObjectCount(doc),
+        };
+    }
+    return null;
+}
 registerTool({
     name: 'request_approval',
     description: 'Request user approval for one or more SAP mutations. Returns approval_ids (one per change) to be passed as approval_id on matching mutating tool calls.',
@@ -135,7 +186,7 @@ registerTool({
                 items: {
                     type: 'object',
                     properties: {
-                        op: { type: 'string', enum: ['create', 'modify', 'delete', 'activate', 'release'] },
+                        op: { type: 'string', enum: ['create', 'modify', 'delete', 'activate', 'release', 'run'] },
                         object: { type: 'string' },
                         type: { type: 'string' },
                         diff: { type: 'string', description: 'For a CREATE op this MUST be the exact, complete source that will be written — verbatim, character-for-character, NOT a description, summary, or paraphrase. It is shown to the developer in the approval box as the exact thing they are approving, so a one-line summary here means they approve a write they cannot inspect. For a MODIFY op, the real unified diff of the change (again verbatim, not a description).' },
@@ -216,6 +267,13 @@ registerTool({
         if (getEffectiveWriteMode(cfg.write_mode, role) === 'advisory-only') {
             return handleAdvisoryApproval(args, { sapAlias: ctx.sapAlias });
         }
+        // Part 3 D12 — a release card carries SAP's own facts about the request,
+        // read here before any card or nag; never the model's. After the advisory
+        // short-circuit (F-10: advisory mints nothing, so no read is spent on a
+        // card that is never drawn). Every refusal mints nothing.
+        const releaseRefusal = await attachReleaseFacts(args.changes ?? [], ctx);
+        if (releaseRefusal)
+            return { content: JSON.stringify(releaseRefusal), is_error: true };
         let sapCfg = cfg.sap[ctx.sapAlias];
         const riskCtx = {
             sapAlias: ctx.sapAlias,

package/dist/tools/hand-off.js

@@ -0,0 +1,86 @@
+/**
+ * hand_off (chat lane, spec 2026-10-17 D5) — the chat's one way into a guided
+ * workflow. Queues `/<skill> <request>` through the existing pendingDispatch
+ * slot (shown as one line "→ /abap-x", never as the person's own line); the
+ * chat turn then ends and the workflow runs with its own plan + approvals.
+ * No extra consent card (D5): the workflow asks before any write.
+ * Refused outside the chat lane; dispatch_skill stays the skills' own switch.
+ *
+ * Flag-gated: only a chat-lane process enables it (Task 11), so a skills-lane
+ * session never lists it and its tools array stays byte-identical to today.
+ */
+import { registerTool } from './index.js';
+import { isPlanResumeCommand } from '../commands/plan-resume.js';
+import { SKILL_CATALOG, resolveSkillAlias } from '../skill-catalog.js';
+/** Longest request hand_off queues (after whitespace is collapsed). */
+export const HAND_OFF_REQUEST_MAX = 500;
+export const HAND_OFF_LINE = (skill) => `→ /${skill}`;
+export const buildHandOffCommand = (skill, request) => `/${skill} ${request}`;
+const CATALOG_NAMES = new Set(SKILL_CATALOG.map((s) => s.name));
+/**
+ * A workflow name as the model wrote it → its catalog name, or null.
+ * Strips one leading `/`, lowercases, resolves a retired alias, and accepts a
+ * bare name ("refactor" → "abap-refactor"). Never `_chat` (not in the catalog).
+ */
+export function normaliseSkill(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const bare = raw.trim().replace(/^\//, '').toLowerCase();
+    if (!bare)
+        return null;
+    for (const candidate of [bare, `abap-${bare}`]) {
+        const resolved = resolveSkillAlias(candidate);
+        if (CATALOG_NAMES.has(resolved))
+            return resolved;
+    }
+    return null;
+}
+registerTool({
+    name: 'hand_off',
+    description: 'Hand this conversation to a CSPeach guided workflow when the developer wants a change made in SAP or a complete deliverable (a full review, a handover document, an upgrade scan). The workflow shows its plan and asks before it writes, so do not ask "shall I hand off?" first — say in one line what you would change, then call this. skill: the workflow name (e.g. "abap-refactor", "abap-generate", "abap-transport", "abap-review"). request: what to do, one clear sentence with object names. After this returns, end the turn.',
+    isMutating: false,
+    flagGated: true,
+    category: 'session',
+    input_schema: {
+        type: 'object',
+        properties: {
+            skill: { type: 'string', description: 'Workflow name without the slash, e.g. "abap-refactor".' },
+            request: { type: 'string', description: 'What the workflow should do, with object names. One sentence, at most 500 characters, no flags.' },
+        },
+        required: ['skill', 'request'],
+    },
+    handler: async (args, ctx) => {
+        const bad = (error, reason) => ({ is_error: true, content: JSON.stringify({ error, reason }) });
+        if (ctx.session?.lane !== 'chat') {
+            return bad('HAND_OFF_OUTSIDE_CHAT', 'hand_off is only for the chat; in a workflow, continue with the workflow (dispatch_skill switches workflows after the person agreed).');
+        }
+        const skill = normaliseSkill(args.skill);
+        if (!skill) {
+            return bad('HAND_OFF_UNKNOWN_SKILL', `unknown workflow "${String(args.skill ?? '')}". Use one of: ${SKILL_CATALOG.map((s) => s.name).join(', ')}`);
+        }
+        const request = typeof args.request === 'string' ? args.request.trim().replace(/\s+/g, ' ') : '';
+        if (!request)
+            return bad('HAND_OFF_INVALID', 'request must say what the workflow should do');
+        if (request.length > HAND_OFF_REQUEST_MAX) {
+            return bad('HAND_OFF_INVALID', `request is too long (${request.length} chars; at most ${HAND_OFF_REQUEST_MAX}). Say it in one short sentence with the object names.`);
+        }
+        const command = buildHandOffCommand(skill, request);
+        if (isPlanResumeCommand(command)) {
+            return bad('PLAN_RESUME_HARNESS_OWNED', 'Plan continuation is owned by CSPeach; never hand off "/abap-plan --resume".');
+        }
+        if (request.startsWith('--')) {
+            return bad('HAND_OFF_INVALID', 'request must start with what to do, not with flags (--…). Say it in one plain sentence with the object names.');
+        }
+        if (!ctx.pendingDispatch) {
+            return bad('DISPATCH_UNSUPPORTED', 'no dispatch slot in this context (one-shot or test); tell the developer which /abap-… command to run instead');
+        }
+        ctx.pendingDispatch.set(command, { by: 'hand_off', line: HAND_OFF_LINE(skill) });
+        return {
+            content: JSON.stringify({
+                ok: true,
+                queued: command,
+                note: 'The workflow runs next and asks before it writes. End the turn now with at most one short line; do not print the command.',
+            }),
+        };
+    },
+});

package/dist/tools/release-texts.js

@@ -0,0 +1,9 @@
+/**
+ * Part 3 — release refusal texts shared by the approval card (approval.ts) and
+ * sap_transport_release (transport.ts). Same words as sap-client's own refusal
+ * in transportRelease; an empty status never prints as an empty string.
+ */
+export function notModifiableText(doc) {
+    return `${doc.number} cannot be released: its status is "${doc.statusText || `status ${doc.status || 'unknown'}`}". `
+        + 'Only a modifiable request can be released. Nothing was sent.';
+}

package/dist/tools/sap-read.js

@@ -29,6 +29,7 @@ import { byObjectTypeForRead } from '../sap/profile-gate.js';
 import { normaliseSyntaxResult, checkSyntax } from './verify.js';
 import { recordSyntaxCheck } from './syntax-state.js';
 import { spillToolResult } from './result-spill.js';
+import { hasManualLocks } from '../sap/session-end.js';
 import { SapError, parseFunctionModuleDocument, parseContainerDocument } from '@cspeach/sap-client';
 // -----------------------------------------------------------------------
 // Task 17 (spec D12, ruling F18) — model-facing formats.
@@ -719,8 +720,11 @@ registerTool({
         required: ['name', 'type'],
     },
     handler: async (args, ctx) => {
-        // runUnitTest(type, name) — type first
-        const result = await ctx.adt.runUnitTest(args.type, args.name);
+        // runUnitTest(type, name, opts) — type first. D18: under a manual lock
+        // (sap_lock) the stateful session is kept, so the lock survives exactly as
+        // before; otherwise sap-client ends an open session first (a stateful
+        // session runs the old load, probe 2026-10-17 §2.3).
+        const result = await ctx.adt.runUnitTest(args.type, args.name, { keepSession: hasManualLocks() });
         // B2 false-green guard: a run in which no test actually ran reads to a
         // caller like "nothing failed → green". Wrap the (still-carried) raw result
         // in an explicit UNVERIFIED envelope when:

package/dist/tools/sap-run.js

@@ -0,0 +1,163 @@
+/**
+ * ADT gap program, Part 3 — sap_run: run one of the person's own classes
+ * (IF_OO_ADT_CLASSRUN) or programs and show the output (plan D1–D8, D18).
+ *
+ * Order (each refusal before anything is spent or sent where it can be):
+ *   0.  Z/Y names only (D3), before the approval.
+ *   0b. Never while a sap_lock lock is held (D18): ending the session would
+ *       drop the lock, keeping it would run the old load. Before the approval.
+ *   1.  One approval of op `run` per run (D2): a plan-grant id never runs, and
+ *       the approval's type must be the type asked for (a CLAS approval never
+ *       runs a PROG of the same name; the jwt checks object/op/nonce only).
+ *   2.  WAL pending entry, as sap_activate writes one.
+ *   3.  runClass / runProgram (sap-client reads SAP's answer: HTTP 200 alone
+ *       is never "ran"; a 500 page is a dump with its window).
+ *   4.  WAL finalized.
+ *   5.  The result: the facts line, then the output, spilled when long (D7).
+ */
+import crypto from 'node:crypto';
+import { registerTool } from './index.js';
+import { verifyAndSpendApprovalId } from '../approvals/jwt.js';
+import { typeCode } from '../approvals/risk-floor.js';
+import { ERR } from '../errors/codes.js';
+import { appendPending, finalizeToolCall } from '../session/pending.js';
+import { hasManualLocks } from '../sap/session-end.js';
+import { spillToolResult } from './result-spill.js';
+import { isCustomerRunnable, notCustomerText, runUrl, SapError } from '@cspeach/sap-client';
+const MANUAL_LOCK_TEXT = 'A lock you took with sap_lock is still held. Unlock it (sap_unlock) first, then ask for the run again.';
+/** Every line right-trimmed (CR included), trailing blank lines dropped. */
+function rightTrimmed(output) {
+    return output.split(/\r?\n/).map((l) => l.trimEnd()).join('\n').trimEnd();
+}
+registerTool({
+    name: 'sap_run',
+    description: 'Run one of your own classes (it must implement IF_OO_ADT_CLASSRUN and be active) or one of your own programs, '
+        + 'and show the output. Only names starting with Z or Y. A program runs with its selection-screen defaults; '
+        + 'values cannot be passed. The run is on the active version. Requires approval_id from a request_approval '
+        + 'change of op `run` (one approval per run; never auto-approved). When SAP answered but did not run anything, '
+        + 'the result says `not_runnable`; when the run dumped, the result says `run_dumped` and gives the window for '
+        + 'sap_short_dump. Long output is saved to a file and previewed.',
+    isMutating: true,
+    requiresSap: true,
+    requires: (a) => (String(a.type ?? '').trim().toUpperCase() === 'PROG' ? 'run.programrun' : 'run.classrun'),
+    input_schema: {
+        type: 'object',
+        properties: {
+            type: { type: 'string', enum: ['CLAS', 'PROG'], description: 'CLAS for a class run (console), PROG for a program run' },
+            name: { type: 'string', description: 'Class or program name, e.g. ZCL_ORDER_DEMO' },
+            approval_id: { type: 'string', description: 'JWT from request_approval (a change of op run)' },
+        },
+        required: ['type', 'name', 'approval_id'],
+    },
+    handler: async (args, ctx) => {
+        const type = String(args.type ?? '').trim().toUpperCase();
+        const rawName = String(args.name ?? '').trim();
+        const name = rawName.toUpperCase();
+        if (type !== 'CLAS' && type !== 'PROG') {
+            return { content: JSON.stringify({ error: 'run_refused', message: 'sap_run runs a class (type CLAS) or a program (type PROG).' }), is_error: true };
+        }
+        // ── 0. Own objects only (D3) — before the approval is spent ────────────
+        // runUrl applies the same rule sap-client applies (and refuses a name that is
+        // not letters, digits and underscores), so nothing it would refuse after the
+        // spend gets past this point.
+        let refusal;
+        if (!rawName || !isCustomerRunnable(rawName))
+            refusal = notCustomerText(rawName);
+        else {
+            try {
+                runUrl(type, rawName);
+            }
+            catch (e) {
+                refusal = e instanceof Error ? e.message : String(e);
+            }
+        }
+        if (refusal) {
+            return { content: JSON.stringify({ error: 'run_refused', message: refusal }), is_error: true };
+        }
+        // ── 0b. Never under a manual lock (D18) — before the approval ──────────
+        if (hasManualLocks()) {
+            return { content: JSON.stringify({ error: 'manual_lock_held', message: MANUAL_LOCK_TEXT }), is_error: true };
+        }
+        // ── 1. The approval: op run, one per run, never a plan grant (D2) ──────
+        const verify = await verifyAndSpendApprovalId(args.approval_id, name, 'run');
+        if (!verify.ok) {
+            return { content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: verify.reason }), is_error: true };
+        }
+        if (verify.payload.grant) {
+            return { content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: 'grant_cannot_run' }), is_error: true };
+        }
+        if (typeCode(verify.payload.type) !== type) {
+            return { content: JSON.stringify({ error: ERR.APPROVAL_INVALID, reason: 'type_mismatch' }), is_error: true };
+        }
+        // ── 2. WAL ─────────────────────────────────────────────────────────────
+        const toolUseId = ctx.toolUseId ?? crypto.randomUUID();
+        const startedAt = Date.now();
+        await appendPending(ctx.session, {
+            tool_use_id: toolUseId,
+            tool: 'sap_run',
+            args: { type, name },
+            started_at: new Date().toISOString(),
+        });
+        const line = (kind, ms) => ctx.chunkEmitter?.emit('info', `run ${type} ${name} · ${kind} · ${ms} ms`);
+        // ── 3. The run ─────────────────────────────────────────────────────────
+        let r;
+        try {
+            r = type === 'PROG' ? await ctx.adt.runProgram(name) : await ctx.adt.runClass(name);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // sap-client's own Z/Y refusal (400) cannot reach here (step 0 ran first).
+            // Anything else (a lost connection) may have run: say so, never "refused".
+            const refused = err instanceof SapError && err.httpStatus === 400;
+            const body = refused
+                ? { error: 'run_refused', message }
+                : { error: 'run_failed', type, name, detail: message };
+            await finalizeToolCall(ctx.session, toolUseId, JSON.stringify(body), true, Date.now() - startedAt);
+            line(refused ? 'refused' : 'failed', Date.now() - startedAt);
+            return { content: JSON.stringify(body), is_error: true };
+        }
+        // ── 4/5. WAL closed, the result ────────────────────────────────────────
+        if (r.kind === 'ran') {
+            const facts = JSON.stringify({
+                ran: true, type, name: r.name, lines: r.lines, chars: r.outputBytes,
+                elapsed_ms: r.elapsedMs, session_ended: r.sessionEnded,
+            });
+            await finalizeToolCall(ctx.session, toolUseId, facts, false, Date.now() - startedAt);
+            line('ran', r.elapsedMs);
+            // The facts line is the first line of the content (not a spill header):
+            // the file starts with it too, so tool_output_read line 1 is the facts.
+            const out = rightTrimmed(r.output);
+            return spillToolResult({ content: out ? `${facts}\n${out}` : facts }, ctx, 'shell', { label: `run ${r.name}` });
+        }
+        let body;
+        if (r.kind === 'not_runnable') {
+            body = {
+                error: 'not_runnable', type, name: r.name, sap_said: r.sapText, reason: r.reason,
+                next_step: 'activate the object (sap_activate) or fix the name, then ask for a new run approval',
+            };
+        }
+        else if (r.kind === 'dumped') {
+            const d = r.dump;
+            body = {
+                error: 'run_dumped', type, name: r.name, message: d?.message,
+                ...(d?.serverTime ? { sap_server_time: d.serverTime } : {}),
+                ...(d?.window ? { dump_window: { from: d.window.from, to: d.window.to } } : {}),
+                note: 'Output written before the exception is lost; the dump has the stack.',
+                next_step: d?.window
+                    ? `sap_short_dump with fromDate and toDate = dump_window (SAP system time), then operation detail on the newest dump whose program names ${r.name}`
+                    : `sap_short_dump (list), then operation detail on the newest dump whose program names ${r.name}`,
+            };
+        }
+        else {
+            body = {
+                error: r.reason?.startsWith('No answer') ? 'run_timed_out' : 'run_failed', type, name: r.name,
+                ...(r.httpStatus !== undefined ? { http_status: r.httpStatus } : {}),
+                detail: r.reason ?? r.sapText,
+            };
+        }
+        const content = JSON.stringify(body);
+        await finalizeToolCall(ctx.session, toolUseId, content, true, Date.now() - startedAt);
+        line(r.kind, r.elapsedMs);
+        return { content, is_error: true };
+    },
+});

package/dist/tools/tool-loading.js

@@ -41,7 +41,7 @@ const FIORI_FAMILY = [
     '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',
+    'sap_transport_create', 'sap_transport_for_object', 'sap_transport_list', 'sap_transport_read', 'sap_transport_release',
 ];
 /**
  * Per-skill starter tools: the non-core tools a skill's body names as its
@@ -65,14 +65,15 @@ export const SKILL_STARTERS = Object.freeze({
     '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'],
+    // Part 3 — the skills whose body says "run it" (Task 7's run block) also start with sap_run.
+    'abap-dump': ['sap_short_dump', 'sap_snapshot_take', 'sap_run'],
+    'abap-incident': ['sap_short_dump', 'sap_snapshot_take', 'sap_atc_run', 'sap_run_unit_test', 'sap_api_state', 'sap_diff', 'sap_run'],
+    'abap-eml': ['sap_run_unit_test', 'sap_run'],
+    'abap-test': ['sap_run_unit_test', 'sap_set_class_include', 'sap_run'],
     'abap-extend-model': ['extend_model_insert', 'sap_snapshot_take', 'sap_service_binding_publish', 'sap_set_class_include'],
     // RAP generator (2026-10-14): SAP's generator writes the stack; the finish check proves F1–F5.
     // Final review M5 — standalone /abap-rap calls rap_skeleton_resolve before it builds.
-    'abap-rap': ['sap_set_class_include', 'sap_service_binding_publish', 'sap_class_includes', 'rap_skeleton_resolve', 'sap_generate_objects', 'rap_finish_check'],
+    'abap-rap': ['sap_set_class_include', 'sap_service_binding_publish', 'sap_class_includes', 'rap_skeleton_resolve', 'sap_generate_objects', 'rap_finish_check', 'sap_run'],
     // Plan steps load tools by the PLAN skill (session.tool_set_skill / params.skill), not the
     // delegate (which only rides as the X-CSPeach-Delegate-Skill header), so the RAP
     // skeleton + finish phases need the generator and the finish check here too.
@@ -84,7 +85,10 @@ export const SKILL_STARTERS = Object.freeze({
     'abap-upgrade-verify': ['sap_atc_run'],
     // Selection texts (2026-10-04): a new PARAMETERS / SELECT-OPTIONS gets its text in the same change.
     'abap-refactor': ['sap_get_text_elements', 'sap_set_text_elements'],
-    'abap-generate': ['sap_get_text_elements', 'sap_set_text_elements'],
+    'abap-generate': ['sap_get_text_elements', 'sap_set_text_elements', 'sap_run'],
+    // Chat lane (D5): the hand-off tool is loaded on chat turns; flag-gated, so a skills-lane session never lists it.
+    // `_chat` is the one SKILL_STARTERS key that is not a catalog skill (pinned in tool-loading.test.ts).
+    '_chat': ['hand_off'],
 });
 /** The starter tools for a skill; unknown skill (or none) ⇒ []. */
 export function startersForSkill(skill) {