@stratusagent/core 0.13.1 → 0.13.3

package/dist/index.js

@@ -425,6 +425,37 @@ const originForSession = (tool, session, input) => {
     const reported = tool.originFor?.(session, input);
     return reported === undefined ? undefined : originOf(reported);
 };
+/** The longest a tool's `trustBeforeCall` may take before the call is judged as reading `external`. */
+export const TRUST_BEFORE_CALL_TIMEOUT_MS = 2_000;
+/**
+ * A tool's `trustBeforeCall` answer, bounded. A throw, a rejection, a label
+ * nobody recognises or no answer in time reads `external`: the call is then
+ * about to read something nobody can vouch for, and judging it as such is
+ * the safe direction. Nothing, for a tool that answers nothing.
+ */
+const trustBeforeCallOf = async (tool, session) => {
+    let timer;
+    try {
+        const label = await Promise.race([
+            Promise.resolve().then(() => tool.trustBeforeCall?.(session)),
+            new Promise((_, reject) => {
+                // Not unref'd: cleared below either way, and an unref'd bound lets a
+                // process with nothing else running exit mid-turn.
+                timer = setTimeout(() => reject(new Error('trustBeforeCall timed out')), TRUST_BEFORE_CALL_TIMEOUT_MS);
+            }),
+        ]);
+        if (label === undefined) {
+            return undefined;
+        }
+        return isTrustLevel(label) ? label : 'external';
+    }
+    catch {
+        return 'external';
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
 /**
  * Whether an agent's `tools:` allowlist permits a tool name.
  *
@@ -1895,6 +1926,15 @@ export const promptTextOf = (message, options = {}) => {
     const framed = `(overheard, not addressed to you)\n${quoted}`;
     return options.latest === true ? `${framed}\n\n${UNADDRESSED_TURN_NOTE}` : framed;
 };
+/**
+ * What separates an overheard message's framed text from its images. The
+ * contract every provider keeps for a message with `overheard` and
+ * images: the text from `promptTextOf` first, then this, then the images,
+ * so pixels never reach a model ahead of the frame that says nobody spoke
+ * to it, and read as that message's attachments rather than as something
+ * the agent was sent. Like the frame, it states the fact, not advice.
+ */
+export const OVERHEARD_IMAGES_NOTE = '(attached to the overheard message above, not addressed to you)';
 /**
  * Whether the turn a session is on is one nobody asked for: its newest
  * user message is overheard, which only `addressed: false` produces at
@@ -2751,6 +2791,64 @@ const MEMORY_RECENT_INTRO = 'Recently remembered:';
 // renders one item per line.
 const renderMemoryTopicLine = (topic) => `- ${escapeControlCharacters(topic.name)} (${topic.count} fact${topic.count === 1 ? '' : 's'},`
     + ` last ${escapeControlCharacters(topic.lastUpdatedAt.slice(0, 10))})`;
+// A date alone is UTC midnight by specification, so it is unambiguous
+// wherever the daemon runs. A *time* without an offset is not: it reads as
+// the host's local zone, so the same requested bound would become a
+// different instant in Los Angeles than in UTC, and a fact would activate
+// or expire at a deployment-dependent hour. So the offset is required
+// whenever a time is given.
+const ISO_8601_INSTANT = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2}))?$/;
+/**
+ * Whether the `YYYY-MM-DD` a bound opens with is a day that exists.
+ *
+ * `Date.parse` normalizes rather than refusing: `2026-02-30` parses fine and
+ * becomes March 2nd, and `2026-02-29` becomes March 1st in a non-leap year.
+ * The regex cannot see it either — both are ISO-*shaped*. A validity window
+ * is the field where that matters most and shows least: the fact starts or
+ * stops being true days from where the writer asked, and the record says
+ * only what it was normalized to.
+ *
+ * Checked on the calendar components as written, never by comparing the
+ * normalized instant back to the string — that was the first attempt at
+ * this and it rejected `2026-04-01T23:00:00-05:00`, whose UTC date is
+ * legitimately the 2nd. An offset is allowed to move the day; February 30th
+ * is not a day.
+ *
+ * `setUTCFullYear` rather than `Date.UTC`, which maps a two-digit year into
+ * the 1900s — the regex admits `0026-02-28`, and that is a real date.
+ */
+const isRealCalendarDate = (raw) => {
+    const [year, month, day] = raw.slice(0, 10).split('-').map(Number);
+    const probe = new Date(0);
+    probe.setUTCFullYear(year, month - 1, day);
+    return probe.getUTCFullYear() === year && probe.getUTCMonth() === month - 1 && probe.getUTCDate() === day;
+};
+/**
+ * Whether a stored time is an ISO-8601 instant that means one thing
+ * everywhere: the shape above, a day that exists, and a value that parses.
+ * The one reading of that rule, for `memory.remember`'s validity bounds and
+ * for the times the memory block shows.
+ */
+export const isIsoInstant = (raw) => ISO_8601_INSTANT.test(raw) && !Number.isNaN(Date.parse(raw)) && isRealCalendarDate(raw);
+/**
+ * A stored time as `YYYY-MM-DD HH:MMZ`, or nothing when it isn't an
+ * unambiguous instant (`isIsoInstant`): `Date` would turn `2026-02-30` into
+ * March 2 and read an offset-less time in the host's zone. Rebuilt from the
+ * parsed instant rather than sliced from the string, so a hand-edited
+ * `createdAt` can only ever render as a time, never as text.
+ */
+const utcMinute = (value) => {
+    if (typeof value !== 'string' || !isIsoInstant(value)) {
+        return undefined;
+    }
+    const iso = new Date(value).toISOString();
+    // An offset can carry year 0000 or 9999 across a UTC year boundary, where
+    // toISOString switches to the six-digit form (Codex P2 4349257583).
+    if (!/^\d{4}-/.test(iso)) {
+        return undefined;
+    }
+    return `${iso.slice(0, 10)} ${iso.slice(11, 16)}Z`;
+};
 /**
  * The memory block: the pinned core, the topic index, and the recency tail,
  * each grouped into trust regions, joined into **one** section.
@@ -2773,7 +2871,17 @@ export const renderMemorySection = (memory) => {
     }
     const injection = asMemoryInjection(memory);
     const blocks = [];
-    const fact = (entry) => `- ${escapeControlCharacters(entry.content)}`;
+    // Each fact says when it was recorded, to the minute: a fact from three
+    // days ago otherwise reads exactly like one from this turn, and live
+    // state (a PR, a deploy) changes within a day. The model is shown
+    // `createdAt` here because it never called recall for these. Stored
+    // times only, never the clock: on the default Anthropic model this
+    // section rides in the system block, which must change only when a
+    // memory does, or every turn's thinking is dropped as a prefix mismatch.
+    const fact = (entry) => {
+        const at = utcMinute(entry.createdAt);
+        return `- ${at ? `(${at}) ` : ''}${escapeControlCharacters(entry.content)}`;
+    };
     const push = (intro, regions) => {
         if (regions.length > 0) {
             blocks.push(`${intro}\n\n${regions.join('\n\n')}`);
@@ -2805,6 +2913,86 @@ export const renderSkillsSection = (skills) => {
     });
     return `You have skills — procedures for doing particular tasks well. When one is relevant to the task at hand, load its full instructions with the ${SKILL_READ_TOOL_NAME} tool (pass the id) and follow them; the one-line descriptions here are pointers, not the procedures themselves:\n${lines.join('\n')}`;
 };
+/**
+ * How hard a Claude model works on a turn, lowest first: the API's
+ * `output_config.effort` and the Agent SDK's `effort` option. A soul's
+ * `effort:` sets it per agent; unset sends nothing, which leaves each
+ * model on its own default.
+ */
+export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+export const isEffortLevel = (value) => typeof value === 'string' && EFFORT_LEVELS.includes(value);
+/**
+ * The effort levels a Claude model takes, or `undefined` for a model this
+ * table does not know (a proxy's name, a model newer than this release).
+ * An empty list is a model known to take no effort at all.
+ *
+ * Kept to families the effort docs name. A model missing here is sent the
+ * configured value as written and reported as unverified, never as applied.
+ */
+/**
+ * A Claude model id with its other established names folded away: a
+ * Bedrock id (`anthropic.` behind any region or `global.` qualifier, a
+ * `-v1:0` suffix) and a Vertex one (`@` and a date), lowercased. Every
+ * check on a model family goes through this, so one that recognizes a
+ * name and another that misses it cannot disagree about the same model.
+ */
+export const claudeModelBase = (model) => model.trim().toLowerCase().replace(/^(?:[a-z0-9-]+\.)*anthropic\./, '').split('@')[0].replace(/-v\d+(?::\d+)?$/, '');
+/**
+ * The highest effort a Claude model takes with thinking disabled, for the
+ * models the effort docs name a ceiling for (Claude Opus 5 and Claude
+ * Haiku 5.5: `high`; above it the API answers 400). `undefined` is no
+ * known ceiling. Kept beside `effortLevelsFor` so both read one id.
+ */
+export const disabledThinkingEffortCeiling = (model) => {
+    const id = claudeModelBase(model);
+    return /^claude-opus-5(-|$)/.test(id) || /^claude-haiku-5-5(-|$)/.test(id) ? 'high' : undefined;
+};
+export const effortLevelsFor = (model) => {
+    // Missed, Opus 4.6 under its Bedrock name asked for xhigh would be sent
+    // xhigh as unverified and refused.
+    const id = claudeModelBase(model);
+    if (/^claude-(opus|sonnet|fable|mythos)-5(-|$)/.test(id) || /^claude-haiku-5-5(-|$)/.test(id) || /^claude-opus-4-[78](-|$)/.test(id)) {
+        return EFFORT_LEVELS;
+    }
+    // Mythos Preview takes max but not xhigh, like the 4.6 models.
+    if (/^claude-(opus|sonnet)-4-6(-|$)/.test(id) || /^claude-mythos-preview(-|$)/.test(id)) {
+        return ['low', 'medium', 'high', 'max'];
+    }
+    if (/^claude-opus-4-5(-|$)/.test(id)) {
+        return ['low', 'medium', 'high'];
+    }
+    if (/^claude-(haiku-4-5|sonnet-4-5|(sonnet|opus)-4(-20\d{6})?$|opus-4-[01](-|$)|3)/.test(id)) {
+        return [];
+    }
+    return undefined;
+};
+export const resolveEffort = (model, requested) => {
+    const levels = effortLevelsFor(model);
+    if (levels === undefined) {
+        return { requested, effort: requested, status: 'unverified' };
+    }
+    if (levels.includes(requested)) {
+        return { requested, effort: requested, status: 'applied' };
+    }
+    const below = EFFORT_LEVELS.slice(0, EFFORT_LEVELS.indexOf(requested)).filter((level) => levels.includes(level));
+    const lowered = below.at(-1);
+    return lowered === undefined
+        ? { requested, status: 'unsupported' }
+        : { requested, effort: lowered, status: 'lowered' };
+};
+/** One line for logs and diagnostics: `high`, `high (asked xhigh; claude-opus-4-6 has no xhigh)`. */
+export const describeEffort = (model, resolution) => {
+    switch (resolution.status) {
+        case 'applied':
+            return resolution.requested;
+        case 'lowered':
+            return `${resolution.effort} (asked ${resolution.requested}; ${model} has no ${resolution.requested})`;
+        case 'unsupported':
+            return `not sent (asked ${resolution.requested}; ${model} takes no effort setting)`;
+        case 'unverified':
+            return `${resolution.requested} (sent; ${model} is not a model Stratus knows the effort levels of)`;
+    }
+};
 /**
  * The language agents write in when nothing says otherwise: American
  * English. A soul's `language:` and the config file's `language` override
@@ -3226,16 +3414,6 @@ export class AllowAllApprovalPolicy {
  * written after read the same.
  */
 const userImages = (images) => images !== undefined && images.length > 0 ? { images } : {};
-/**
- * See `RunInput.addressed`: an image reaches the model as pixels, before
- * and outside the text that frames what was said as somebody else's, so
- * a turn nobody asked for takes none.
- */
-const refuseUnaddressedImages = (input) => {
-    if (input.addressed === false && input.images !== undefined && input.images.length > 0) {
-        throw new Error('A turn nobody asked for cannot carry images: an image enters the prompt ahead of the frame that marks the message as somebody else\'s. Name the attachment in the message instead.');
-    }
-};
 /**
  * Thrown by a provider when the request did not fit the model's context
  * window — the transcript, not the answer, is what was too long.
@@ -3561,7 +3739,6 @@ export class AgentRunner {
         await this.plugins.loadAll({ bus: this.bus, tools: this.tools });
     }
     async run(input) {
-        refuseUnaddressedImages(input);
         // The sender's trust is the turn's, not the session's: it is read here
         // and kept out of the persisted metadata, where a later reader would
         // take the first sender's label for every turn that follows.
@@ -3648,7 +3825,6 @@ export class AgentRunner {
         }
     }
     async resume(input) {
-        refuseUnaddressedImages(input);
         const session = await this.store.get(input.sessionId);
         if (!session) {
             throw new Error(`Session not found: ${input.sessionId}`);
@@ -4575,6 +4751,19 @@ export class AgentRunner {
             if (problem) {
                 return rejected(`Invalid input for ${call.toolName}: ${problem}. Fix the call and try again.`);
             }
+            // A call the tool already knows it will refuse, answered here for the
+            // same reason: nobody should be asked to approve it. A hook that
+            // throws is no answer, and the call goes on to be judged as before.
+            let refusal;
+            try {
+                refusal = await tool.refusalFor?.(call.input, session);
+            }
+            catch {
+                refusal = undefined;
+            }
+            if (typeof refusal === 'string' && refusal.trim().length > 0) {
+                return rejected(refusal.trim());
+            }
         }
         // 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
@@ -4617,17 +4806,52 @@ export class AgentRunner {
          * unaffected.
          */
         let originWhenJudged;
+        // What the call may read, lowered into the session before the policy
+        // reads the session's label, so the decision covers this call and not
+        // only the next one. Asked again after an approval, because a human's
+        // answer can take minutes and the label can drop in that time; one
+        // re-decision, then a refusal, so a label that keeps moving cannot
+        // hold the call in a loop of questions.
+        const lowerBeforeCall = async () => {
+            if (!tool.trustBeforeCall) {
+                return undefined;
+            }
+            const label = await trustBeforeCallOf(tool, session);
+            if (label !== undefined) {
+                await this.taint(session, label, call.toolName);
+            }
+            return label;
+        };
         let approved;
+        let decidedTrust = sessionTrustOf(session);
+        let movedTwice = false;
         try {
-            approved = await this.approvals.approve({
-                session,
-                call,
-                tool,
-                risk,
-                ...(signal ? { signal } : {}),
-                ...(options.parkedAt ? { parkedAt: options.parkedAt } : {}),
-            });
-            originWhenJudged = originForSession(tool, session, call.input);
+            await lowerBeforeCall();
+            const decide = async () => {
+                decidedTrust = sessionTrustOf(session);
+                const answer = await this.approvals.approve({
+                    session,
+                    call,
+                    tool,
+                    risk,
+                    ...(signal ? { signal } : {}),
+                    ...(options.parkedAt ? { parkedAt: options.parkedAt } : {}),
+                });
+                // With nothing awaited since the policy returned (see above).
+                originWhenJudged = originForSession(tool, session, call.input);
+                return answer;
+            };
+            approved = await decide();
+            if (approved && tool.trustBeforeCall) {
+                const dropped = async () => {
+                    const label = await lowerBeforeCall();
+                    return label !== undefined && leastTrusted(decidedTrust, label) !== decidedTrust;
+                };
+                if (await dropped()) {
+                    approved = await decide();
+                    movedTwice = approved && await dropped();
+                }
+            }
         }
         finally {
             // Cleared before anything executes and on every exit — an abort that
@@ -4637,6 +4861,18 @@ export class AgentRunner {
                 await this.checkpointPendingApproval(session, undefined);
             }
         }
+        if (movedTwice) {
+            await this.bus.emit({ type: 'tool.denied', sessionId: session.id, call });
+            return {
+                callId: call.id,
+                toolName: call.toolName,
+                ok: false,
+                output: null,
+                error: `${call.toolName} did not run: what it may read was marked less trusted twice while it was being approved. `
+                    + 'Call again to have it judged as things stand now.',
+                trust: 'agent',
+            };
+        }
         if (!approved) {
             await this.bus.emit({ type: 'tool.denied', sessionId: session.id, call });
             return {
@@ -4675,6 +4911,7 @@ export class AgentRunner {
         const collector = createImageCollector();
         const executed = await this.executor.execute(call, tool, session, {
             ...(signal ? { signal } : {}),
+            decidedTrust,
             attachImage: collector.attach,
         });
         // Only a call that succeeded shows what it attached: a failure's error