@lucascouts/claude-agent-acp-plus 0.27.0 → 0.29.0

package/dist/ultracode.js

@@ -1,103 +1,236 @@
 /**
- * The "Ultracode" entry of the Effort picker.
+ * Ultracode — an independent, session-scoped boolean option.
  *
- * **Ultracode is not a sixth effort level, and reading it as one produces the
- * wrong control.** Claude Code's VS Code extension models it as a boolean that
- * turns on two things at once — `xhigh` effort *and* standing dynamic-workflow
- * orchestration — and its own tooltip says so: `"Ultracode - xhigh +
- * workflows"`. Its five real levels are `low` `medium` `high` `xhigh` `max`;
- * Ultracode is drawn as one extra notch past the last of them, styled
- * differently, and selecting any ordinary level clears it.
+ * **What it is.** The SDK's `Settings.ultracode` is *"standing
+ * dynamic-workflow orchestration at any effort level"*, session-scoped and
+ * applied through `apply_flag_settings`. It is not an effort level and it does
+ * not imply one: the CLI (`/effort ultracode on|off`, "any effort level, this
+ * session only") and the VS Code extension (a switch in the effort popover)
+ * both model it as a toggle beside effort. An earlier version of this module
+ * followed an older extension tooltip ("xhigh + workflows") and drew it as a
+ * notch in the effort select that forced `xhigh`; that silently raised the
+ * effort of a session started with `ultracode: true`, cleared it on any effort
+ * pick, and lost it on a model switch (PARITY-REPORT §21.2).
  *
- * ACP has no compound control to carry that, so the adapter projects it the way
- * the extension's UI reads rather than the way its state is stored: one more
- * entry in the `effort` select. The compound stays here, in one module, instead
- * of being spread across the three places `acp-agent.ts` applies effort.
+ * **The wire contract** (`applyFlagSettings`, unchanged SDK 0.3.285..0.3.299):
+ * - `ultracode: true|false` turns it on or off and leaves effort alone;
+ * - an `effortLevel` change sent WITHOUT the key turns it off;
+ * - `null` resets it to off.
+ * Hence the two payload rules below: the toggle sends `{ultracode:true}` or
+ * `{ultracode:null}`, and every effort change re-sends `ultracode:true` while
+ * the intent is on — and never `null`.
  *
- * The SDK carries both halves and names the channel: `Settings.ultracode` is
- * *"xhigh effort plus standing dynamic-workflow orchestration. Session-scoped —
- * typically provided via --settings or the apply_flag_settings control
- * request"*. `apply_flag_settings` is already how the effort option is applied,
- * so no new transport is involved.
+ * **Intent is not availability.** The CLI keeps the request and computes "in
+ * effect = requested and available", where available means workflows are
+ * enabled and the model supports `xhigh`. The adapter mirrors that: the
+ * session holds the intent, the option is shown only while available, and a
+ * model switch never drops the intent. The CLI reports both through the
+ * `get_settings` control request (`applied.{ultracode, ultracodeRequested,
+ * ultracodeAvailable}`), which the SDK runtime exposes as `Query.getSettings()`
+ * but `sdk.d.ts` does not declare — {@link readUltracodeState} wraps it.
  *
  * Kept self-contained — no import from `acp-agent.ts` — for the reason
- * `thinking-option.ts` and `rewind-command.ts` state: that file is ~9,900 lines
- * and moves upstream almost daily, so every coupling to it is paid again at
- * each sync.
+ * `thinking-option.ts` and `rewind-command.ts` state: that file is ~10,000
+ * lines and moves upstream almost daily, so every coupling to it is paid again
+ * at each sync.
  */
-/** Value of the synthetic "Ultracode" entry in the effort picker. It is a
- *  reserved sentinel: no `EffortLevel` is spelled this way, so it cannot
- *  collide with a level the SDK reports in `supportedEffortLevels`. */
-export const ULTRACODE_OPTION_VALUE = "ultracode";
-/** Display name of that entry, matching the extension's own label. */
+/** Config option id. */
+export const ULTRACODE_CONFIG_ID = "ultracode";
+/** Display name, matching the CLI's and the extension's label. */
 export const ULTRACODE_OPTION_NAME = "Ultracode";
-/** The effort level Ultracode implies. Not configurable: the extension hardcodes
- *  `xhigh` in `enableUltracode()`, and the SDK's own description of the setting
- *  names the same level. A different level here would silently mean something
- *  else than it does in the reference client. */
+const ULTRACODE_DESCRIPTION = "Run dynamic workflows on every task";
+/** Select-fallback values for clients without boolean config options. The
+ *  same spelling Fast mode uses, so one client-side mapping serves both. */
+export const ULTRACODE_ON = "on";
+export const ULTRACODE_OFF = "off";
+/** The effort level the model must support for Ultracode to be available.
+ *  Availability only: Ultracode never SETS this level. */
 export const ULTRACODE_EFFORT_LEVEL = "xhigh";
+/** The value the old effort-select notch carried. Accepted for one release
+ *  from clients that still send it (see {@link isLegacyUltracodeEffort}). */
+export const LEGACY_ULTRACODE_EFFORT_VALUE = "ultracode";
 /**
- * Whether the Ultracode entry may be offered, under the same two conditions the
- * extension checks in its own `ultracodeAvailable`:
+ * The fallback availability check, used until (or instead of) the CLI's own
+ * `applied.ultracodeAvailable`:
  *
- * 1. workflows are not disabled — Ultracode *is* the workflow half, so offering
- *    it where `disableWorkflows` is set would advertise something that cannot
- *    happen;
- * 2. the current model supports `xhigh` — Ultracode has no meaning on a model
- *    that cannot reach the level it implies.
+ * 1. workflows are not disabled — Ultracode *is* workflow orchestration;
+ * 2. the current model supports `xhigh`.
  *
- * Both are read rather than assumed: an unknown settings shape leaves
- * `disableWorkflows` undefined, which is *not* `true`, so the gate opens — the
- * same direction the extension's `=== !0` comparison takes.
+ * Partial by nature: the CLI also checks managed settings, org policy,
+ * `enableWorkflows` and `CLAUDE_CODE_DISABLE_WORKFLOWS`. An absent
+ * `disableWorkflows` opens the gate, the same direction the extension's
+ * `=== !0` comparison takes.
  */
 export function isUltracodeAvailable(supportedEffortLevels, settings) {
     if (settings?.disableWorkflows === true)
         return false;
     return supportedEffortLevels.includes(ULTRACODE_EFFORT_LEVEL);
 }
-/** Whether a picker value denotes Ultracode rather than a plain effort level. */
-export function isUltracodeValue(value) {
-    return value === ULTRACODE_OPTION_VALUE;
+/** Build the option: a native boolean for clients that opted in, an on/off
+ *  select otherwise (the ACP boolean-config-option RFD makes that a MUST). */
+export function createUltracodeConfigOption(requested, useBooleanOption) {
+    const base = {
+        id: ULTRACODE_CONFIG_ID,
+        name: ULTRACODE_OPTION_NAME,
+        description: ULTRACODE_DESCRIPTION,
+        category: "model_config",
+    };
+    if (useBooleanOption) {
+        return { ...base, type: "boolean", currentValue: requested };
+    }
+    return {
+        ...base,
+        type: "select",
+        currentValue: requested ? ULTRACODE_ON : ULTRACODE_OFF,
+        options: [
+            { value: ULTRACODE_ON, name: "On" },
+            { value: ULTRACODE_OFF, name: "Off" },
+        ],
+    };
+}
+/** The option for a resolved state, or `undefined` while unavailable. */
+export function ultracodeConfigOption(state) {
+    if (!state?.available)
+        return undefined;
+    return createUltracodeConfigOption(state.requested, state.useBooleanOption);
+}
+/**
+ * Put the option where it belongs in an existing list — right after `effort`
+ * (after `model` when the model has no effort option), before `fast` — or
+ * remove it when `next` is undefined. Used when a background readback changes
+ * availability without a full rebuild.
+ */
+export function placeUltracodeOption(options, next) {
+    const rest = options.filter((o) => o.id !== ULTRACODE_CONFIG_ID);
+    if (!next)
+        return rest;
+    let anchor = rest.findIndex((o) => o.id === "effort");
+    if (anchor < 0)
+        anchor = rest.findIndex((o) => o.id === "model");
+    const at = anchor < 0 ? rest.length : anchor + 1;
+    return [...rest.slice(0, at), next, ...rest.slice(at)];
+}
+/** Resolve the requested value from `session/set_config_option`: a native
+ *  boolean, or the on/off select-fallback strings. */
+export function resolveUltracodeRequested(params) {
+    const value = params.value;
+    if (typeof value === "boolean")
+        return value;
+    if (value === ULTRACODE_ON)
+        return true;
+    if (value === ULTRACODE_OFF)
+        return false;
+    throw new Error(`Invalid value for config option ${ULTRACODE_CONFIG_ID}: ${String(value)}`);
+}
+/** The toggle's payload. Off is an explicit `null`: `undefined` is dropped by
+ *  JSON transport, and the SDK only clears a flag on `null`. */
+export function ultracodeTogglePayload(requested) {
+    return { ultracode: requested ? true : null };
 }
 /**
- * The `apply_flag_settings` payload for an effort selection, Ultracode included.
+ * The `apply_flag_settings` payload for an effort change — a user pick, the
+ * model-switch fallback, the initial effort, or a recreate's replay.
  *
- * **The `null` is the load-bearing part.** The SDK shallow-merges flag settings
- * and only clears a key when an explicit `null` arrives — `undefined` is dropped
- * by JSON transport and leaves the previous value standing. So every selection
- * has to say something about `ultracode`, not just the one that turns it on:
- * without the clear, picking `High` after Ultracode would lower the effort and
- * leave workflow orchestration running, which is a state no picker entry names.
- * The same reasoning applies to `effortLevel` — this function absorbed the older
- * `toSdkEffortLevel` helper for exactly that reason: both keys are decided in
- * one place, so neither can be forgotten on a path the other takes.
+ * An `effortLevel` change sent without `ultracode` turns Ultracode off, so the
+ * key rides along whenever the intent is on. It is never sent as `null` here:
+ * an effort change is not a request to turn Ultracode off.
  *
- * @param value the picker value — `"default"`, an `EffortLevel`, or the
- *   Ultracode sentinel. `undefined` means the option is absent for this model.
+ * @param value the effort select's value — `"default"`, an `EffortLevel`, or
+ *   `undefined` when the model has no effort option.
  */
-export function ultracodeFlagSettings(value) {
-    if (isUltracodeValue(value)) {
-        return { effortLevel: ULTRACODE_EFFORT_LEVEL, ultracode: true };
-    }
-    return {
-        effortLevel: value === undefined || value === "default" ? null : value,
-        ultracode: null,
-    };
+export function effortFlagSettings(value, ultracodeRequested) {
+    const effortLevel = value === undefined || value === "default" ? null : value;
+    return ultracodeRequested ? { effortLevel, ultracode: true } : { effortLevel };
+}
+/** Whether an effort value is the retired Ultracode notch. Clients that saved
+ *  it get `{effortLevel:'xhigh', ultracode:true}` for one release. */
+export function isLegacyUltracodeEffort(value) {
+    return value === LEGACY_ULTRACODE_EFFORT_VALUE;
 }
 /**
- * The picker value to display, given the persisted effort level and whether the
- * Ultracode flag is on.
+ * Read `applied.{ultracodeRequested, ultracodeAvailable}` through the SDK's
+ * untyped `Query.getSettings()`.
+ *
+ * Structural, never trusting: an SDK without the method, a rejected request,
+ * or a response without `applied` all resolve to `undefined`, and the caller
+ * keeps the heuristic. Never rejects.
  *
- * The flag wins over the level, and only when it is *available*: a session that
- * carries `ultracode: true` from settings while the current model cannot reach
- * `xhigh` must not show an entry the picker is not rendering. The extension
- * reaches the same state through `adoptAppliedEffort`, which reads
- * `applied.ultracode` first and falls back to inferring it from `xhigh`; we do
- * not infer, because `xhigh` alone is a legitimate selection that is not
- * Ultracode, and guessing would silently turn workflows on in the label.
+ * **Call it in the background, never inline.** Control requests are
+ * serialized and queue ahead of interrupt and close (upstream #1216), and on a
+ * fresh session the CLI does not service them until the first turn.
+ */
+export async function readUltracodeState(query, onError) {
+    const getSettings = query?.getSettings;
+    if (typeof getSettings !== "function")
+        return undefined;
+    let response;
+    try {
+        response = await getSettings.call(query);
+    }
+    catch (error) {
+        onError?.(error);
+        return undefined;
+    }
+    const applied = response?.applied;
+    if (typeof applied !== "object" || applied === null)
+        return undefined;
+    const { ultracodeRequested, ultracodeAvailable } = applied;
+    const readback = {};
+    if (typeof ultracodeRequested === "boolean")
+        readback.requested = ultracodeRequested;
+    if (typeof ultracodeAvailable === "boolean")
+        readback.available = ultracodeAvailable;
+    return readback.requested === undefined && readback.available === undefined
+        ? undefined
+        : readback;
+}
+/** Rebuild the option in place from the session's state. */
+export function refreshUltracodeOption(session, useBooleanOption) {
+    session.configOptions = placeUltracodeOption(session.configOptions, ultracodeConfigOption({
+        available: session.ultracodeAvailable,
+        requested: session.ultracodeRequested,
+        useBooleanOption,
+    }));
+}
+/** Toggle the intent. Applies first, then records — a rejected control
+ *  request leaves the session and its option untouched, as Fast mode does. */
+export async function applyUltracodeToggle(session, requested, useBooleanOption) {
+    await session.query.applyFlagSettings(ultracodeTogglePayload(requested));
+    session.ultracodeRequested = requested;
+    refreshUltracodeOption(session, useBooleanOption);
+}
+/**
+ * The one-release migration for clients that still send the retired notch:
+ * `effort = "ultracode"` becomes `{effortLevel:'xhigh', ultracode:true}`.
+ * Returns `false`, sending nothing, when this model's effort select does not
+ * offer `xhigh` — the caller then rejects the value like any other.
  */
-export function effortOptionValue(effortLevel, ultracode) {
-    if (ultracode?.available && ultracode.enabled)
-        return ULTRACODE_OPTION_VALUE;
-    return effortLevel;
+export async function applyLegacyUltracodeEffort(session, useBooleanOption) {
+    const effort = session.configOptions.find((o) => o.id === "effort");
+    const offersXhigh = effort?.type === "select" &&
+        effort.options.some((o) => "value" in o && o.value === ULTRACODE_EFFORT_LEVEL);
+    if (!offersXhigh)
+        return false;
+    await session.query.applyFlagSettings(effortFlagSettings(ULTRACODE_EFFORT_LEVEL, true));
+    session.ultracodeRequested = true;
+    session.configOptions = session.configOptions.map((o) => o.id === "effort" && o.type === "select" ? { ...o, currentValue: ULTRACODE_EFFORT_LEVEL } : o);
+    refreshUltracodeOption(session, useBooleanOption);
+    return true;
+}
+/**
+ * Fold a CLI readback into the session. Availability is always taken; the
+ * intent only when `seedIntent` (session start — a model switch keeps the
+ * intent it has). Returns whether the option the client sees changed, i.e.
+ * whether a `config_option_update` is owed.
+ */
+export function applyUltracodeReadback(session, readback, seedIntent, useBooleanOption) {
+    const before = JSON.stringify(session.configOptions.find((o) => o.id === ULTRACODE_CONFIG_ID));
+    if (readback.available !== undefined)
+        session.ultracodeAvailable = readback.available;
+    if (seedIntent && readback.requested !== undefined) {
+        session.ultracodeRequested = readback.requested;
+    }
+    refreshUltracodeOption(session, useBooleanOption);
+    const after = JSON.stringify(session.configOptions.find((o) => o.id === ULTRACODE_CONFIG_ID));
+    return before !== after;
 }

package/dist/usage-markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-markdown.d.ts","sourceRoot":"","sources":["../src/usage-markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAKxF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AA6DjD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,GAAG,IAAI,CAOpF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAU1E;AA0OD,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CAS7E;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,KAAK,EACL,2DAA2D,CAC5D,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,mBAAmB,GAAG;IAAE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,CAAC;AAQvE;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwDxB"}
+{"version":3,"file":"usage-markdown.d.ts","sourceRoot":"","sources":["../src/usage-markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAKxF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AA6DjD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,GAAG,IAAI,CAOpF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAU1E;AAmSD,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CAS7E;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,KAAK,EACL,2DAA2D,CAC5D,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,mBAAmB,GAAG;IAAE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,CAAC;AAQvE;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwDxB"}

package/dist/usage-markdown.js

@@ -227,8 +227,65 @@ function appendLimit(lines, label, window) {
 }
 /** How many MCP servers one contribution table lists. */
 const TOP_CONTRIBUTIONS = 3;
+/**
+ * Labels for the usage patterns (`behaviors[].key`) the pinned SDK types
+ * define, worded as Claude Code's own `/usage` dialog words them (CLI 2.1.285:
+ * "41% of your usage hit a >100k-token cache miss"). A key not listed here — a
+ * newer CLI adds them ahead of the SDK types — renders from its own name, so it
+ * shows without a code change.
+ */
+const BEHAVIOR_LABELS = {
+    cache_miss: "Hit a >100k-token cache miss",
+    long_context: "At >150k context",
+    subagent_heavy: "Subagent-heavy sessions",
+    high_parallel: "While 4+ sessions ran in parallel",
+    cron: "Sessions active for 8+ hours",
+};
+/** `max_effort` -> "Max effort", escaped: the key is the CLI's, not ours. */
+function behaviorLabel(key) {
+    const known = BEHAVIOR_LABELS[key];
+    if (known !== undefined)
+        return known;
+    const words = key.replace(/_+/g, " ").trim();
+    return escapeMarkdown(words.charAt(0).toUpperCase() + words.slice(1));
+}
+/**
+ * A period's usage patterns, read defensively: the schema does not validate
+ * `behaviors[]`, so a report from a CLI that reshaped it still renders
+ * everything else. An entry with no usable key or share is skipped, and so is
+ * one with no share at all — the CLI sends every pattern it knows, most at 0%.
+ */
+function readBehaviors(period) {
+    const raw = period?.behaviors;
+    if (!Array.isArray(raw))
+        return [];
+    const rows = [];
+    for (const entry of raw) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const { key, pct, count } = entry;
+        if (typeof key !== "string" || key.trim() === "")
+            continue;
+        if (typeof pct !== "number" || !Number.isFinite(pct) || pct <= 0)
+            continue;
+        rows.push({
+            key,
+            pct,
+            count: typeof count === "number" && Number.isFinite(count) && count >= 0 ? count : null,
+        });
+    }
+    return rows.sort((a, b) => b.pct - a.pct);
+}
 function appendContributions(lines, label, period) {
     lines.push("", `**${label}** \u00b7 ${period.request_count} requests \u00b7 ${period.session_count} sessions`);
+    const behaviors = readBehaviors(period);
+    if (behaviors.length > 0) {
+        lines.push("", "| Usage pattern | Usage | Requests |", "|:--|--:|--:|");
+        for (const behavior of behaviors) {
+            const bar = usageBar(normalizeUtilization(behavior.pct) ?? 0);
+            lines.push(`| ${behaviorLabel(behavior.key)} | \`${bar}\` ${behavior.pct}% | ${behavior.count ?? "\u2014"} |`);
+        }
+    }
     if (period.mcp_servers.length === 0) {
         return;
     }

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Claude Code in Zed and other ACP clients with the VS Code extension's UX — multi-select questions, refusal consent, live quota windows, background tasks, Ultracode effort and session notices. Fork of claude-agent-acp.",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",