@compilr-dev/sdk 0.23.0 → 0.23.2

package/dist/team/team-agent.d.ts

@@ -13,6 +13,38 @@ import type { ModelTier } from '../models/index.js';
 import type { ProviderType } from '../config.js';
 import type { SharedContextManager } from './shared-context.js';
 import type { CustomAgentDefinition } from './custom-agents.js';
+/**
+ * Strip the composite a pre-0.23 `fromRole()` stored, so it is not composed a second time.
+ *
+ * ⚠️ WITHOUT THIS, EVERY ROLE AGENT CREATED BEFORE 0.23 SENDS ITS ROLE PROMPT TWICE. The first
+ * cut of this migration skipped role agents, reasoning that an edited stored prompt is
+ * indistinguishable from an unedited one so removing anything risks the user's text. True, and
+ * beside the point: the generated sections now compose on top of whatever is stored, so leaving
+ * the legacy copy in place duplicates it. Measured on a real `$arch`: 13,024 characters instead
+ * of ~6,900, with the role header and capability blurb appearing twice each.
+ *
+ * ⚠️ AND IT CANNOT WORK BY RECONSTRUCTION. The second cut rebuilt the old composite exactly and
+ * stripped it on an exact match. That matched 6 of 16 real agents. The capability blurb lists
+ * the profile's tool GROUPS as they stood on the day the agent was created — a `qa` agent saved
+ * before the profile gained `consult` carries a blurb nine characters shorter than today's, and
+ * no amount of care reproduces a list that has since changed.
+ *
+ * So this anchors on the two ends, which are stable, and ignores the drifting middle entirely:
+ *
+ *   - the FIRST LINE must be the first line of generated content (the role header, or the
+ *     guidance heading for roles with no role prompt of their own), and
+ *   - the CURRENT guidance block must appear — it is always last, and unlike the tool blurb it
+ *     is not derived from mutable configuration.
+ *
+ * Everything up to the end of that guidance is generated; whatever follows is the user's and is
+ * kept. If either anchor is missing the value is returned untouched, so hand-written text and a
+ * future rewording both fail safe: the agent keeps its duplication until someone clears the box,
+ * and nobody loses text they wrote.
+ *
+ * @returns the user's own remainder, `undefined` if the stored value was entirely generated, or
+ *          `stored` unchanged when it is not recognisably a legacy composite.
+ */
+export declare function splitLegacyRolePrompt(stored: string, role: AgentRole): string | undefined;
 /**
  * The editable subset of an agent.
  *
@@ -240,6 +272,28 @@ export declare class TeamAgent {
      * `thought_signature`) that do not transfer across a rebuild.
      */
     private stashForRebuild;
+    /**
+     * A turn is in flight: the host has called `run()`/`stream()` and is awaiting it.
+     *
+     * ⚠️ HOSTS MUST BRACKET EVERY RUN, IN A `finally`. `TeamAgent` does not own the run call —
+     * the host holds the unwrapped `Agent` — so it cannot observe this for itself.
+     */
+    private turnStartedAt;
+    /**
+     * How long a turn may be in flight before this stops believing the host.
+     *
+     * ⚠️ A FLAG THAT ONLY EVER GETS SET IS WORSE THAN THE BUG IT GUARDS. A host that throws past
+     * its `endTurn()` would block every edit to that agent for the life of the process, with no
+     * way back short of a restart. Going stale bounds that to one window; the edit that slips
+     * through after it is the same edit that would have been allowed before this guard existed.
+     */
+    private static readonly TURN_STALE_AFTER_MS;
+    /** Mark the start of a turn. Pair with `endTurn()` in a `finally`. */
+    beginTurn(): void;
+    /** Mark the end of a turn, however it ended — completed, aborted or thrown. */
+    endTurn(): void;
+    /** Whether a turn is in flight and recent enough to still be believed. */
+    get isTurnInFlight(): boolean;
     /**
      * Apply an edit to this agent in place.
      *

package/dist/team/team-agent.js

@@ -11,6 +11,58 @@ import { ROLE_METADATA } from './types.js';
 import { getModelForTier, getModelContextWindow } from '../models/index.js';
 import { generateCustomAgentScaffold, getCustomAgentToolFilter, splitLegacyCustomPrompt, } from './custom-agents.js';
 import { getToolsForProfile, PROFILE_INFO, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, } from './tool-config.js';
+/**
+ * Strip the composite a pre-0.23 `fromRole()` stored, so it is not composed a second time.
+ *
+ * ⚠️ WITHOUT THIS, EVERY ROLE AGENT CREATED BEFORE 0.23 SENDS ITS ROLE PROMPT TWICE. The first
+ * cut of this migration skipped role agents, reasoning that an edited stored prompt is
+ * indistinguishable from an unedited one so removing anything risks the user's text. True, and
+ * beside the point: the generated sections now compose on top of whatever is stored, so leaving
+ * the legacy copy in place duplicates it. Measured on a real `$arch`: 13,024 characters instead
+ * of ~6,900, with the role header and capability blurb appearing twice each.
+ *
+ * ⚠️ AND IT CANNOT WORK BY RECONSTRUCTION. The second cut rebuilt the old composite exactly and
+ * stripped it on an exact match. That matched 6 of 16 real agents. The capability blurb lists
+ * the profile's tool GROUPS as they stood on the day the agent was created — a `qa` agent saved
+ * before the profile gained `consult` carries a blurb nine characters shorter than today's, and
+ * no amount of care reproduces a list that has since changed.
+ *
+ * So this anchors on the two ends, which are stable, and ignores the drifting middle entirely:
+ *
+ *   - the FIRST LINE must be the first line of generated content (the role header, or the
+ *     guidance heading for roles with no role prompt of their own), and
+ *   - the CURRENT guidance block must appear — it is always last, and unlike the tool blurb it
+ *     is not derived from mutable configuration.
+ *
+ * Everything up to the end of that guidance is generated; whatever follows is the user's and is
+ * kept. If either anchor is missing the value is returned untouched, so hand-written text and a
+ * future rewording both fail safe: the agent keeps its duplication until someone clears the box,
+ * and nobody loses text they wrote.
+ *
+ * @returns the user's own remainder, `undefined` if the stored value was entirely generated, or
+ *          `stored` unchanged when it is not recognisably a legacy composite.
+ */
+export function splitLegacyRolePrompt(stored, role) {
+    /*
+      ⚠️ TYPED AS TOTAL, NOT TOTAL AT RUNTIME. `role` is `AgentRole` to the compiler but arrives
+      from a JSON file on disk, so it can be any string — a role removed in a later version, or one
+      a fixture invented. The explicit `| undefined` is what makes the guard below legitimate
+      rather than "always falsy": lint reasons from the type, and the type is a claim about data
+      we do not control.
+    */
+    const byRole = ROLE_METADATA;
+    const metadata = byRole[role];
+    if (!metadata)
+        return stored;
+    const guidance = role === 'default' ? generateCoordinatorGuidance() : generateSpecialistGuidance(role);
+    const generatedFirstLine = (metadata.defaultSystemPromptAddition || guidance).split('\n')[0];
+    if (stored.split('\n')[0] !== generatedFirstLine)
+        return stored;
+    const at = stored.lastIndexOf(guidance);
+    if (at === -1)
+        return stored;
+    return stored.slice(at + guidance.length).trim() || undefined;
+}
 /**
  * Estimate token count from text (approximate: ~4 chars per token)
  */
@@ -285,6 +337,36 @@ export class TeamAgent {
         this.storedState = state;
         this._agent = null;
     }
+    /**
+     * A turn is in flight: the host has called `run()`/`stream()` and is awaiting it.
+     *
+     * ⚠️ HOSTS MUST BRACKET EVERY RUN, IN A `finally`. `TeamAgent` does not own the run call —
+     * the host holds the unwrapped `Agent` — so it cannot observe this for itself.
+     */
+    turnStartedAt = null;
+    /**
+     * How long a turn may be in flight before this stops believing the host.
+     *
+     * ⚠️ A FLAG THAT ONLY EVER GETS SET IS WORSE THAN THE BUG IT GUARDS. A host that throws past
+     * its `endTurn()` would block every edit to that agent for the life of the process, with no
+     * way back short of a restart. Going stale bounds that to one window; the edit that slips
+     * through after it is the same edit that would have been allowed before this guard existed.
+     */
+    static TURN_STALE_AFTER_MS = 10 * 60 * 1000;
+    /** Mark the start of a turn. Pair with `endTurn()` in a `finally`. */
+    beginTurn() {
+        this.turnStartedAt = Date.now();
+    }
+    /** Mark the end of a turn, however it ended — completed, aborted or thrown. */
+    endTurn() {
+        this.turnStartedAt = null;
+    }
+    /** Whether a turn is in flight and recent enough to still be believed. */
+    get isTurnInFlight() {
+        if (this.turnStartedAt === null)
+            return false;
+        return Date.now() - this.turnStartedAt < TeamAgent.TURN_STALE_AFTER_MS;
+    }
     /**
      * Apply an edit to this agent in place.
      *
@@ -308,6 +390,25 @@ export class TeamAgent {
           when it is not. Its `rebuilt` contribution is folded in below.
         */
         const tierChanged = patch.modelTier !== undefined && patch.modelTier !== this._modelTier;
+        /*
+          ⚠️ REFUSED MID-TURN, BEFORE ANYTHING IS MUTATED. A rebuild snapshots the history with
+          `serialize()` and drops the instance — but the in-flight `run()` holds its own reference
+          and finishes anyway, appending to an agent nobody will read again. Measured: the user
+          watches a reply stream in, and the rebuilt agent is handed the snapshot from BEFORE it,
+          with no memory of having said it.
+    
+          Not a broken conversation — `setHistory` repairs tool pairing, so nothing 400s. It is
+          worse than that: the agent silently forgets a turn the user just watched, and the next
+          thing it says is built on a history the user can see is wrong.
+    
+          Only rebuilding edits are refused. A rename or a new face is read from the roster at
+          render time and cannot tear anything, so those still apply mid-turn.
+        */
+        if ((needsRebuild || tierChanged) && this.isTurnInFlight) {
+            throw new Error(`Agent '${this.id}' is mid-reply. Changing its prompt, model, tools or skills rebuilds ` +
+                `it and would drop the turn it is in the middle of — wait for the reply to finish, ` +
+                `or stop it, then save.`);
+        }
         if (patch.modelTier !== undefined)
             this.setModelTier(patch.modelTier);
         if (patch.displayName !== undefined)
@@ -670,6 +771,9 @@ export class TeamAgent {
                 personality = personality ?? legacy.personality;
             }
         }
+        else if (data.role !== 'custom' && systemPromptAddition) {
+            systemPromptAddition = splitLegacyRolePrompt(systemPromptAddition, data.role);
+        }
         const agent = new TeamAgent({
             id: data.id,
             displayName: data.displayName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.23.0",
+  "version": "0.23.2",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",