@stratusagent/core 0.11.7 → 0.11.9

package/dist/index.js

@@ -354,7 +354,16 @@ export const UNTRUSTED_TOOL_RESULT_NOTE = 'This result was written by a party th
  * transcripts, where a changed byte is a cache miss.
  */
 export const renderToolResultContent = (result) => {
-    const output = result.ok ? result.output : { error: result.error ?? 'Tool failed' };
+    // A failure keeps what the tool returned with it. A shell command that
+    // exits 1 carries its stdout, stderr, and exit code, and without them the
+    // model cannot tell a failing test from a typo from a missing program, so
+    // it guesses or asks. A failure with no output renders exactly as before,
+    // so most persisted transcripts replay byte-identical.
+    const output = result.ok
+        ? result.output
+        : result.output === null || result.output === undefined
+            ? { error: result.error ?? 'Tool failed' }
+            : { error: result.error ?? 'Tool failed', output: result.output };
     return JSON.stringify(result.trust === 'external'
         ? { untrusted: true, untrustedNote: UNTRUSTED_TOOL_RESULT_NOTE, output }
         : output);
@@ -412,8 +421,8 @@ export const originOf = (rawUrl) => {
  * as written, so every comparison of an origin in this codebase is of the
  * same thing.
  */
-const originForSession = (tool, session) => {
-    const reported = tool.originFor?.(session);
+const originForSession = (tool, session, input) => {
+    const reported = tool.originFor?.(session, input);
     return reported === undefined ? undefined : originOf(reported);
 };
 /**
@@ -1498,6 +1507,9 @@ const CONVERSATION_KINDS = ['direct', 'group', 'private', 'public'];
 // vouched for, but still typed, so anything that is not plainly a name is
 // dropped rather than quoted.
 const CONVERSATION_WITH_PATTERN = /^[\p{L}\p{M}\p{N}][\p{L}\p{M}\p{N} .'\u2019-]{0,63}$/u;
+// A platform-assigned id, never a word anyone typed: Slack's are capitals
+// and digits. Anything else is dropped rather than quoted.
+const CONVERSATION_ID_PATTERN = /^[A-Z0-9]{6,32}$/;
 /**
  * The room a turn's metadata describes, keeping only what is safe to put
  * in front of the model, or undefined when it describes none.
@@ -1507,7 +1519,7 @@ export const conversationContextFrom = (metadata) => {
     if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
         return undefined;
     }
-    const { kind, members, with: withWhom, thread, shared } = raw;
+    const { kind, members, with: withWhom, thread, shared, id } = raw;
     if (typeof kind !== 'string' || !CONVERSATION_KINDS.includes(kind)) {
         return undefined;
     }
@@ -1517,6 +1529,7 @@ export const conversationContextFrom = (metadata) => {
         ...(kind === 'direct' && typeof withWhom === 'string' && CONVERSATION_WITH_PATTERN.test(withWhom.trim()) ? { with: withWhom.trim() } : {}),
         ...(thread === true ? { thread: true } : {}),
         ...(kind !== 'direct' && shared === true ? { shared: true } : {}),
+        ...(kind !== 'direct' && typeof id === 'string' && CONVERSATION_ID_PATTERN.test(id) ? { id } : {}),
     };
 };
 /**
@@ -1543,6 +1556,66 @@ export const transcriptOf = (request) => request.messages ?? request.session.mes
  * in config, that an auditor can see.
  */
 export const DEFAULT_SUBPROCESS_PASS_ENV = ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TZ'];
+/**
+ * Collects what a tool attaches through `ExecutionContext.attachImage`,
+ * held to the limits that sink documents.
+ */
+export const createImageCollector = () => {
+    const images = [];
+    let total = 0;
+    return {
+        attach: (image) => {
+            if (!isImageAttachmentMediaType(image.mediaType)) {
+                throw new Error(`An image of type ${String(image.mediaType)} cannot be shown to the model; it takes ${IMAGE_ATTACHMENT_MEDIA_TYPES.join(', ')}.`);
+            }
+            const bytes = Buffer.from(image.data, 'base64');
+            if (bytes.length === 0) {
+                throw new Error('The image is empty.');
+            }
+            if (bytes.length > IMAGE_ATTACHMENT_MAX_BYTES) {
+                throw new Error(`The image is ${bytes.length} bytes, over the ${IMAGE_ATTACHMENT_MAX_BYTES}-byte limit for one image.`);
+            }
+            if (total + bytes.length > IMAGE_ATTACHMENTS_MAX_TOTAL_BYTES) {
+                throw new Error(`One call can return at most ${IMAGE_ATTACHMENTS_MAX_TOTAL_BYTES} bytes of images.`);
+            }
+            const dimensions = imageDimensions(bytes, image.mediaType);
+            if (dimensions === undefined) {
+                throw new Error(`The bytes are not a complete ${image.mediaType} image.`);
+            }
+            if (dimensions.width > IMAGE_ATTACHMENT_MAX_DIMENSION || dimensions.height > IMAGE_ATTACHMENT_MAX_DIMENSION) {
+                throw new Error(`The image is ${dimensions.width}×${dimensions.height}, over the ${IMAGE_ATTACHMENT_MAX_DIMENSION}-pixel side the model can take.`);
+            }
+            total += bytes.length;
+            images.push({ mediaType: image.mediaType, data: image.data, ...(image.name !== undefined ? { name: image.name } : {}) });
+        },
+        images: () => [...images],
+    };
+};
+/**
+ * The transcript message for a tool result: its images moved off the
+ * result onto the message, where the replay budget and the trim already
+ * look, so the stored content and the result stay text.
+ */
+const toolResultMessage = (session, result) => {
+    const { images, ...stored } = result;
+    return {
+        id: `${session.id}:tool:${result.callId}`,
+        role: 'tool',
+        name: result.toolName,
+        content: JSON.stringify(stored),
+        createdAt: new Date().toISOString(),
+        toolResult: stored,
+        ...(images !== undefined && images.length > 0 ? { images } : {}),
+    };
+};
+/** A result as the bus carries it: never the image bytes. */
+const withoutImages = (result) => {
+    if (result.images === undefined) {
+        return result;
+    }
+    const { images: _images, ...rest } = result;
+    return rest;
+};
 /** Where a parked turn's checkpoint lives in `session.metadata`. */
 export const PENDING_APPROVAL_METADATA_KEY = 'pendingApproval';
 /**
@@ -2809,6 +2882,7 @@ export const renderChannelSection = (session, conversation) => {
  */
 const describeRoom = (room, channel) => {
     const count = room.members !== undefined ? room.members.toLocaleString('en-US') : undefined;
+    const idNote = room.id !== undefined ? ` Its ${channel} id is ${room.id}.` : '';
     const inThread = room.thread === true ? ' You are replying in a thread there, which everyone who can read the channel can open.' : '';
     const outside = room.shared === true
         ? ' It is shared with people outside this workspace, through Slack Connect or another workspace of the organization, and they read it too.'
@@ -2821,13 +2895,13 @@ const describeRoom = (room, channel) => {
                 + 'Only the two of you can read it, so you are talking to one person.';
         case 'group':
             return `this is a group direct message in ${channel}${count !== undefined ? ` with ${count} members, you included` : ''}. `
-                + `Only they can read it.${outside}${inThread} ${forEveryone}`;
+                + `Only they can read it.${idNote}${outside}${inThread} ${forEveryone}`;
         case 'private':
             return `this is a private ${channel} channel${count !== undefined ? ` with ${count} members, you included` : ''}. `
-                + `Only its members can read it.${outside}${inThread} ${forEveryone}`;
+                + `Only its members can read it.${idNote}${outside}${inThread} ${forEveryone}`;
         case 'public':
             return `this is a public ${channel} channel${count !== undefined ? ` with ${count} members` : ''}. `
-                + `Anyone in the workspace can find it and read it, now or later, not only the people talking.${outside}${inThread} ${forEveryone}`;
+                + `Anyone in the workspace can find it and read it, now or later, not only the people talking.${idNote}${outside}${inThread} ${forEveryone}`;
     }
 };
 // A provider or model name as the prompt may carry it. A model name can
@@ -3293,6 +3367,87 @@ const throwIfAborted = (signal) => {
  * task checks in rather than where it dies, and 40 is enough for real
  * multi-step work while still bounding what a runaway loop can spend.
  */
+/**
+ * What is wrong with a call's input against the shape its tool declared,
+ * or undefined when nothing the check reads is wrong.
+ *
+ * Deliberately shallow: required keys, the declared JSON types, `enum`,
+ * and `additionalProperties: false`, applied to nested objects too. It
+ * exists so a call the tool would reject anyway is answered with the reason
+ * before anyone is asked to approve it, not to replace a tool's own checks,
+ * which still run. A schema keyword it doesn't read is not a failure.
+ */
+/** JSON equality, member order aside, the way JSON Schema compares `enum` values. */
+const sameJson = (left, right, depth = 0) => {
+    if (left === right) {
+        return true;
+    }
+    // Past any depth a real enum has, too deep to compare safely: unknown is
+    // not wrong, so it counts as a match and the tool's own checks decide.
+    if (depth > 64) {
+        return true;
+    }
+    if (left === null || right === null || typeof left !== 'object' || typeof right !== 'object') {
+        return false;
+    }
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((item, index) => sameJson(item, right[index], depth + 1));
+    }
+    const leftKeys = Object.keys(left).filter((key) => left[key] !== undefined);
+    const rightKeys = Object.keys(right).filter((key) => right[key] !== undefined);
+    return leftKeys.length === rightKeys.length && leftKeys.every((key) => sameJson(left[key], right[key], depth + 1));
+};
+export const inputProblem = (schema, input, where = 'input', depth = 0) => {
+    if (schema === undefined || depth > 4) {
+        return undefined;
+    }
+    const declared = schema.type;
+    const types = Array.isArray(declared) ? declared.filter((type) => typeof type === 'string') : typeof declared === 'string' ? [declared] : [];
+    if (types.length > 0) {
+        const actual = input === null ? 'null'
+            : Array.isArray(input) ? 'array'
+                : typeof input === 'number' ? (Number.isInteger(input) ? 'integer' : 'number')
+                    : typeof input;
+        const fits = types.some((type) => type === actual || (type === 'number' && actual === 'integer'));
+        if (!fits) {
+            return `${where} should be ${types.join(' or ')}, not ${actual}`;
+        }
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some((option) => sameJson(option, input))) {
+        return `${where} should be one of ${schema.enum.map((option) => JSON.stringify(option)).join(', ')}`;
+    }
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        return undefined;
+    }
+    const properties = schema.properties !== null && typeof schema.properties === 'object' && !Array.isArray(schema.properties)
+        ? schema.properties
+        : {};
+    for (const key of Array.isArray(schema.required) ? schema.required : []) {
+        if (typeof key === 'string' && input[key] === undefined) {
+            return `${where} is missing "${key}"`;
+        }
+    }
+    // With `patternProperties` a key may be declared by a pattern, and running
+    // a pattern a schema supplied is a regex engine on untrusted input. Not
+    // this check's job: extra keys are only judged when no pattern exists.
+    const patterned = schema.patternProperties !== undefined && schema.patternProperties !== null;
+    if (schema.additionalProperties === false && !patterned) {
+        const unknown = Object.keys(input).find((key) => !(key in properties));
+        if (unknown !== undefined) {
+            return `${where} has "${unknown}", which this tool does not take (it takes ${Object.keys(properties).map((key) => `"${key}"`).join(', ') || 'nothing'})`;
+        }
+    }
+    for (const [key, value] of Object.entries(input)) {
+        const property = properties[key];
+        if (value !== undefined && property !== null && typeof property === 'object' && !Array.isArray(property)) {
+            const problem = inputProblem(property, value, `${where}.${key}`, depth + 1);
+            if (problem) {
+                return problem;
+            }
+        }
+    }
+    return undefined;
+};
 export const DEFAULT_MAX_TURNS = 40;
 export class AgentRunner {
     bus;
@@ -3340,11 +3495,23 @@ export class AgentRunner {
         // and kept out of the persisted metadata, where a later reader would
         // take the first sender's label for every turn that follows.
         const { [SENDER_TRUST_METADATA_KEY]: _sender, ...persisted } = input.metadata ?? {};
-        const senderTrust = senderTrustOf(input.metadata);
+        const earlier = input.earlier ?? [];
+        // Everyone whose words open the transcript, not only the one who
+        // asked: see `RunInput.earlier`.
+        const senderTrust = earlier.reduce((lowest, entry) => leastTrusted(lowest, senderTrustOf(entry.metadata)), senderTrustOf(input.metadata));
+        const createdAt = new Date().toISOString();
+        const heard = earlier.map((entry, index) => ({
+            id: `${input.sessionId}:user:${index + 1}`,
+            role: 'user',
+            content: entry.message,
+            createdAt,
+            overheard: true,
+            observed: true,
+        }));
         // The first stored turn is held to the window like every later one:
         // a one-shot session is a row too.
         const opening = {
-            id: `${input.sessionId}:user:1`,
+            id: `${input.sessionId}:user:${heard.length + 1}`,
             role: 'user',
             content: input.userMessage,
             createdAt: new Date().toISOString(),
@@ -3358,7 +3525,7 @@ export class AgentRunner {
             id: input.sessionId,
             agent: input.agent,
             status: 'running',
-            messages: [opening],
+            messages: [...heard, opening],
             // Labelled from the first write, whatever the dispatching surface
             // put in `metadata` under this key: the label is the runner's to
             // write, and a fresh session starts at the top of the lattice lowered
@@ -4126,14 +4293,8 @@ export class AgentRunner {
      * longer re-enterable, the two facts belong in one write.
      */
     async recordToolResult(session, result) {
-        session.messages.push({
-            id: `${session.id}:tool:${result.callId}`,
-            role: 'tool',
-            name: result.toolName,
-            content: JSON.stringify(result),
-            createdAt: new Date().toISOString(),
-            toolResult: result,
-        });
+        session.messages.push(toolResultMessage(session, result));
+        omitImagesOutsideReplayBudget(session.messages, this.imageReplayBudget);
         if (readPendingApproval(session)?.call.id === result.callId) {
             const metadata = { ...(session.metadata ?? {}) };
             delete metadata[PENDING_APPROVAL_METADATA_KEY];
@@ -4200,14 +4361,8 @@ export class AgentRunner {
             ...(context?.signal ? { signal: context.signal } : {}),
             recoverable: false,
         });
-        session.messages.push({
-            id: `${session.id}:tool:${result.callId}`,
-            role: 'tool',
-            name: result.toolName,
-            content: JSON.stringify(result),
-            createdAt: new Date().toISOString(),
-            toolResult: result,
-        });
+        session.messages.push(toolResultMessage(session, result));
+        omitImagesOutsideReplayBudget(session.messages, this.imageReplayBudget);
         await this.store.save(session);
         return result;
     }
@@ -4282,6 +4437,17 @@ export class AgentRunner {
         if (!tool) {
             return rejected(`Tool not found: ${call.toolName}`);
         }
+        // A malformed call is answered before anyone is asked about it, for the
+        // reason an unknown tool is: approving a call the tool will reject is a
+        // question with no useful answer, and the model needs the reason, not a
+        // human's click, to fix it. Only for calls that would be asked about; a
+        // `safe` tool's own checks answer it as they always have.
+        if (resolveToolRisk(tool) !== 'safe') {
+            const problem = inputProblem(tool.parameters, call.input);
+            if (problem) {
+                return rejected(`Invalid input for ${call.toolName}: ${problem}. Fix the call and try again.`);
+            }
+        }
         // Only a call that can actually be held for a human is checkpointed:
         // a `safe` one is never asked about, and writing a record for it would
         // add a save to every unattended call to describe a wait that does not
@@ -4333,7 +4499,7 @@ export class AgentRunner {
                 ...(signal ? { signal } : {}),
                 ...(options.parkedAt ? { parkedAt: options.parkedAt } : {}),
             });
-            originWhenJudged = originForSession(tool, session);
+            originWhenJudged = originForSession(tool, session, call.input);
         }
         finally {
             // Cleared before anything executes and on every exit — an abort that
@@ -4363,7 +4529,7 @@ export class AgentRunner {
         // `tool.completed` keeps the pairing every consumer reads — the
         // watchdog's phase, the channel's live line. The agent is told plainly,
         // because this is a page that moved rather than a permission it lacks.
-        const originNow = originForSession(tool, session);
+        const originNow = originForSession(tool, session, call.input);
         if (originNow !== originWhenJudged) {
             const result = {
                 callId: call.id,
@@ -4378,7 +4544,15 @@ export class AgentRunner {
             await this.bus.emit({ type: 'tool.completed', sessionId: session.id, result });
             return result;
         }
-        const result = await this.executor.execute(call, tool, session, signal ? { signal } : undefined);
+        const collector = createImageCollector();
+        const executed = await this.executor.execute(call, tool, session, {
+            ...(signal ? { signal } : {}),
+            attachImage: collector.attach,
+        });
+        // Only a call that succeeded shows what it attached: a failure's error
+        // is the result, and an image ahead of it would read as the answer.
+        const attached = executed.ok ? collector.images() : [];
+        const result = attached.length > 0 ? { ...executed, images: attached } : withoutImages(executed);
         // Where tools execute, not in the provider loop above: this path also
         // serves `executeHostedToolCall`, through which `provider-claude-code`
         // and `provider-codex` run their bridged kernel tools. A hook in
@@ -4387,7 +4561,7 @@ export class AgentRunner {
         // wrong. An executor that returned no label is read as `unknown` —
         // absence of provenance is not evidence of trust, here either.
         await this.taint(session, result.trust ?? 'unknown', call.toolName);
-        await this.bus.emit({ type: 'tool.completed', sessionId: session.id, result });
+        await this.bus.emit({ type: 'tool.completed', sessionId: session.id, result: withoutImages(result) });
         return result;
     }
 }