@stigmer/cli 3.12.8 → 3.13.0

package/src/resources/run/prepare.test.ts

@@ -5,7 +5,7 @@
 import { describe, expect, it } from "vitest";
 import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { Stigmer } from "@stigmer/sdk";
-import { type AgentExecFlags, parseApprovalAction, prepareAgentExec, validateMode, validateServiceTier, validateThinking } from "./prepare.js";
+import { type AgentExecFlags, parseApprovalAction, prepareAgentExec, validateHarness, validateMode, validateServiceTier, validateThinking } from "./prepare.js";
 
 describe("parseApprovalAction", () => {
   it("maps each accepted value (case-insensitive)", () => {
@@ -59,6 +59,24 @@ describe("validateThinking", () => {
   });
 });
 
+describe("validateHarness", () => {
+  it("accepts empty, native, and cursor", () => {
+    expect(() => validateHarness("")).not.toThrow();
+    expect(() => validateHarness("native")).not.toThrow();
+    expect(() => validateHarness("cursor")).not.toThrow();
+  });
+
+  it("rejects anything else before a network round trip", () => {
+    expect(() => validateHarness("turbo")).toThrow(/must be "native" or "cursor"/);
+  });
+
+  it("rejects UI-only harness names that have no proto mapping", () => {
+    // copilot/codex/etc. exist in display metadata but not on the wire —
+    // accepting them here would stamp UNSPECIFIED and silently run native.
+    expect(() => validateHarness("copilot")).toThrow(/must be "native" or "cursor"/);
+  });
+});
+
 const BASE_FLAGS: AgentExecFlags = {
   message: "hi",
   attach: [],
@@ -77,23 +95,35 @@ const BASE_FLAGS: AgentExecFlags = {
   mode: "",
   serviceTier: "",
   thinking: "",
+  harness: "",
 };
 
 // prepareAgentExec only touches client.agentExecution for attachment uploads;
 // with no attachments a bare stub suffices.
 const STUB_CLIENT = { agentExecution: {} } as unknown as Stigmer;
 
-/** Stub whose whoAmI resolves an account carrying the given preference. */
-function clientWithPreference(defaultNativeModel: string): Stigmer {
+/** The shape of IdentityAccountPreferences the stubs below expose. */
+interface StubPreferences {
+  readonly defaultHarness?: string;
+  readonly defaultNativeModel?: string;
+  readonly defaultCursorModel?: string;
+}
+
+/** Stub whose whoAmI resolves an account carrying the given preferences. */
+function clientWithPreferences(preferences: StubPreferences): Stigmer {
   return {
     agentExecution: {},
     identityAccount: {
-      whoAmI: () =>
-        Promise.resolve({ spec: { preferences: { defaultNativeModel } } }),
+      whoAmI: () => Promise.resolve({ spec: { preferences } }),
     },
   } as unknown as Stigmer;
 }
 
+/** Back-compat shorthand for the original native-model-only stub. */
+function clientWithPreference(defaultNativeModel: string): Stigmer {
+  return clientWithPreferences({ defaultNativeModel });
+}
+
 /** Stub whose whoAmI rejects (auth failure, backend without the RPC, ...). */
 function clientWithFailingWhoAmI(): Stigmer {
   return {
@@ -104,6 +134,24 @@ function clientWithFailingWhoAmI(): Stigmer {
   } as unknown as Stigmer;
 }
 
+/** Preference stub that also counts whoAmI invocations (round-trip pin). */
+function countingClient(preferences: StubPreferences): { client: Stigmer; calls: () => number } {
+  let calls = 0;
+  const client = {
+    agentExecution: {},
+    identityAccount: {
+      whoAmI: () => {
+        calls += 1;
+        return Promise.resolve({ spec: { preferences } });
+      },
+    },
+  } as unknown as Stigmer;
+  return { client, calls: () => calls };
+}
+
+/** prepareAgentExec options as `run` passes them: cloud + harness opt-in. */
+const CLOUD_RUN_OPTIONS = { cloudBackend: true, applyAccountHarnessDefault: true } as const;
+
 describe("prepareAgentExec env injection", () => {
   it("injects STIGMER_ORG_ID when absent", async () => {
     const prepared = await prepareAgentExec(BASE_FLAGS, STUB_CLIENT, "acme");
@@ -196,3 +244,197 @@ describe("prepareAgentExec account-preference model fill (oss#293 Phase 1.5)", (
     expect(prepared.model).toBe("");
   });
 });
+
+describe("prepareAgentExec harness resolution (oss#293)", () => {
+  it("fills an omitted --harness from the account preference on cloud when the caller opts in (run)", async () => {
+    const prepared = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithPreferences({ defaultHarness: "cursor" }),
+      "acme",
+      undefined,
+      CLOUD_RUN_OPTIONS,
+    );
+    expect(prepared.harness).toBe("cursor");
+  });
+
+  it("an explicit --harness always outranks the account preference", async () => {
+    // The per-run escape hatch: a cursor-preference user can still force a
+    // native run without touching their settings.
+    const prepared = await prepareAgentExec(
+      { ...BASE_FLAGS, harness: "native" },
+      clientWithPreferences({ defaultHarness: "cursor" }),
+      "acme",
+      undefined,
+      CLOUD_RUN_OPTIONS,
+    );
+    expect(prepared.harness).toBe("native");
+  });
+
+  it("ignores the preference when the caller has not opted in (draft, D5)", async () => {
+    // draft runs the seedpack's system creator agents — a utility flow that
+    // must not be silently rerouted onto the cursor engine by a preference
+    // meant for the user's own sessions (owner-ratified D5).
+    const prepared = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithPreferences({ defaultHarness: "cursor" }),
+      "acme",
+      undefined,
+      { cloudBackend: true },
+    );
+    expect(prepared.harness).toBe("");
+  });
+
+  it("an explicit --harness still resolves for a non-opted-in caller (draft escape hatch)", async () => {
+    const prepared = await prepareAgentExec(
+      { ...BASE_FLAGS, harness: "cursor" },
+      STUB_CLIENT,
+      "acme",
+      undefined,
+      { cloudBackend: false },
+    );
+    expect(prepared.harness).toBe("cursor");
+  });
+
+  it("treats a malformed persisted harness as undeclared", async () => {
+    // A client must not trust stored data it did not write: anything outside
+    // the shipped allowlist resolves as if no preference existed.
+    const prepared = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithPreferences({ defaultHarness: "devin" }),
+      "acme",
+      undefined,
+      CLOUD_RUN_OPTIONS,
+    );
+    expect(prepared.harness).toBe("");
+  });
+
+  it("resolves empty when whoAmI fails — a missing preference never fails a run", async () => {
+    const prepared = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithFailingWhoAmI(),
+      "acme",
+      undefined,
+      CLOUD_RUN_OPTIONS,
+    );
+    expect(prepared.harness).toBe("");
+    expect(prepared.model).toBe("");
+  });
+
+  it("never consults identity on a local backend, even with the opt-in", async () => {
+    // The failing stub doubles as a call detector, as in the model-fill suite.
+    const prepared = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithFailingWhoAmI(),
+      "acme",
+      undefined,
+      { cloudBackend: false, applyAccountHarnessDefault: true },
+    );
+    expect(prepared.harness).toBe("");
+  });
+
+  it("resolves empty when nothing is declared anywhere", async () => {
+    const prepared = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithPreferences({}),
+      "acme",
+      undefined,
+      CLOUD_RUN_OPTIONS,
+    );
+    expect(prepared.harness).toBe("");
+  });
+});
+
+describe("prepareAgentExec harness-aware model fill (oss#293)", () => {
+  const BOTH_MODELS: StubPreferences = {
+    defaultNativeModel: "claude-sonnet-4.6",
+    defaultCursorModel: "composer-2.5",
+  };
+
+  it("fills the cursor model when the explicit harness is cursor", async () => {
+    const prepared = await prepareAgentExec(
+      { ...BASE_FLAGS, harness: "cursor" },
+      clientWithPreferences(BOTH_MODELS),
+      "acme",
+      undefined,
+      CLOUD_RUN_OPTIONS,
+    );
+    expect(prepared.model).toBe("composer-2.5");
+  });
+
+  it("fills the cursor model when the preference resolves the harness to cursor", async () => {
+    const prepared = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithPreferences({ ...BOTH_MODELS, defaultHarness: "cursor" }),
+      "acme",
+      undefined,
+      CLOUD_RUN_OPTIONS,
+    );
+    expect(prepared.harness).toBe("cursor");
+    expect(prepared.model).toBe("composer-2.5");
+  });
+
+  it("fills the native model when the harness resolves native or empty", async () => {
+    const explicit = await prepareAgentExec(
+      { ...BASE_FLAGS, harness: "native" },
+      clientWithPreferences(BOTH_MODELS),
+      "acme",
+      undefined,
+      CLOUD_RUN_OPTIONS,
+    );
+    expect(explicit.model).toBe("claude-sonnet-4.6");
+
+    const unset = await prepareAgentExec(
+      BASE_FLAGS,
+      clientWithPreferences(BOTH_MODELS),
+      "acme",
+      undefined,
+      CLOUD_RUN_OPTIONS,
+    );
+    expect(unset.model).toBe("claude-sonnet-4.6");
+  });
+
+  it("an explicit --model outranks the harness-matched preference", async () => {
+    const prepared = await prepareAgentExec(
+      { ...BASE_FLAGS, harness: "cursor", model: "gpt-5.3" },
+      clientWithPreferences(BOTH_MODELS),
+      "acme",
+      undefined,
+      CLOUD_RUN_OPTIONS,
+    );
+    expect(prepared.model).toBe("gpt-5.3");
+  });
+
+  it("draft with an explicit --harness cursor fills the cursor model despite no harness opt-in (D5)", async () => {
+    // D5 scopes only the silent preference fill; the model fill follows
+    // whatever harness the user explicitly chose.
+    const prepared = await prepareAgentExec(
+      { ...BASE_FLAGS, harness: "cursor" },
+      clientWithPreferences(BOTH_MODELS),
+      "acme",
+      undefined,
+      { cloudBackend: true },
+    );
+    expect(prepared.harness).toBe("cursor");
+    expect(prepared.model).toBe("composer-2.5");
+  });
+
+  it("serves both fills from one whoAmI round trip, and none when both flags are explicit", async () => {
+    const single = countingClient({ ...BOTH_MODELS, defaultHarness: "cursor" });
+    const filled = await prepareAgentExec(BASE_FLAGS, single.client, "acme", undefined, CLOUD_RUN_OPTIONS);
+    expect(filled.harness).toBe("cursor");
+    expect(filled.model).toBe("composer-2.5");
+    expect(single.calls(), "harness + model fills share one whoAmI").toBe(1);
+
+    const skipped = countingClient(BOTH_MODELS);
+    const explicit = await prepareAgentExec(
+      { ...BASE_FLAGS, harness: "native", model: "gpt-5.3" },
+      skipped.client,
+      "acme",
+      undefined,
+      CLOUD_RUN_OPTIONS,
+    );
+    expect(explicit.harness).toBe("native");
+    expect(explicit.model).toBe("gpt-5.3");
+    expect(skipped.calls(), "explicit flags leave nothing to fill — no round trip").toBe(0);
+  });
+});

package/src/resources/run/prepare.ts

@@ -32,6 +32,15 @@ export type ServiceTierFlag = "" | "standard" | "fast";
  */
 export type ThinkingFlag = "" | "disabled" | "enabled";
 
+/**
+ * The `--harness` flag's value space (oss#293): empty means unset — the
+ * account preference may fill it (see {@link prepareAgentExec}), and when
+ * nothing resolves the server defaults the session to native. Deliberately
+ * only the two shipped engines, mirroring the proto validation on
+ * `IdentityAccountPreferences.default_harness`.
+ */
+export type HarnessFlag = "" | "native" | "cursor";
+
 /** Raw agent-execution flags shared by `run` and `draft` (Go's agentExecFlags). */
 export interface AgentExecFlags {
   readonly message: string;
@@ -51,6 +60,7 @@ export interface AgentExecFlags {
   readonly mode: RunMode;
   readonly serviceTier: ServiceTierFlag;
   readonly thinking: ThinkingFlag;
+  readonly harness: HarnessFlag;
 }
 
 /**
@@ -71,6 +81,13 @@ export interface PreparedRun {
   readonly mode: RunMode;
   readonly serviceTier: ServiceTierFlag;
   readonly thinking: ThinkingFlag;
+  /**
+   * The RESOLVED harness for the new session: the explicit flag, else the
+   * account preference (when the caller opted in), else "" — which stays off
+   * the wire so the server default (native) applies. Also drives the header's
+   * visibility row: a cursor session is never entered silently.
+   */
+  readonly harness: HarnessFlag;
 }
 
 /** Optional behavior switches for {@link prepareAgentExec}. */
@@ -78,11 +95,24 @@ export interface PrepareAgentExecOptions {
   /**
    * When `true` (the caller's backend is Stigmer Cloud) and `--model` is
    * omitted, the model is filled from the caller's account preference
-   * (`IdentityAccountPreferences.default_native_model`) via `whoAmI()`.
-   * Local mode has no IdentityAccount, so callers pass `false` there and
-   * the omitted model keeps resolving to the platform default.
+   * (`IdentityAccountPreferences.default_*_model` for the resolved harness)
+   * via `whoAmI()`. Local mode has no IdentityAccount, so callers pass
+   * `false` there and the omitted model keeps resolving to the platform
+   * default.
    */
   readonly cloudBackend?: boolean;
+  /**
+   * When `true` and `--harness` is omitted, the harness is filled from the
+   * caller's account preference (`IdentityAccountPreferences.default_harness`)
+   * on cloud. `run` opts in; `draft` deliberately does not: draft executes the
+   * seedpack's system creator agents (a utility flow, not the user's own
+   * conversation), which are built and exercised on the native harness —
+   * silently rerouting them onto the cursor engine (different toolset,
+   * premium billing tier) would fail the least-surprise test. An explicit
+   * `--harness` on draft still wins; only the silent preference fill is
+   * scoped out. Owner-ratified (D5, 2026-08-23).
+   */
+  readonly applyAccountHarnessDefault?: boolean;
 }
 
 /**
@@ -100,16 +130,28 @@ export async function prepareAgentExec(
   validateMode(flags.mode);
   validateServiceTier(flags.serviceTier);
   validateThinking(flags.thinking);
+  validateHarness(flags.harness);
 
-  // Layered model seed (oss#293 Phase 1.5): an explicit --model always wins;
-  // an omitted one fills from the account preference on cloud. `run` and
-  // `draft` always create a NEW session (threading lives in `resume`, which
-  // does not pass through here), so the fill never injects a native model
-  // into an existing cursor-harness session.
-  const model =
-    flags.model === "" && options?.cloudBackend === true
-      ? await resolveModelFromAccountPreference(client)
-      : flags.model;
+  // Layered seeds (oss#293, DD-003): explicit flag > account preference
+  // (cloud only) > platform default. Harness resolves first because the model
+  // fill is harness-aware: a cursor session fills from default_cursor_model,
+  // everything else from default_native_model. `run` and `draft` always
+  // create a NEW session (threading lives in `resume`, which does not pass
+  // through here), so neither fill can ever contradict an existing session's
+  // immutable harness. One whoAmI round trip serves both fills, and it is
+  // skipped entirely when explicit flags leave nothing to fill.
+  const wantsHarnessFill = flags.harness === "" && options?.applyAccountHarnessDefault === true;
+  const wantsModelFill = flags.model === "";
+  const accountDefaults =
+    options?.cloudBackend === true && (wantsHarnessFill || wantsModelFill)
+      ? await resolveAccountExecutionDefaults(client)
+      : NO_ACCOUNT_DEFAULTS;
+  const harness = flags.harness !== "" ? flags.harness : wantsHarnessFill ? accountDefaults.harness : "";
+  const model = wantsModelFill
+    ? harness === "cursor"
+      ? accountDefaults.cursorModel
+      : accountDefaults.nativeModel
+    : flags.model;
 
   const workspaceEntries = parseWorkspaceEntries(flags.workspace, flags.branch, flags.commit);
 
@@ -144,23 +186,43 @@ export async function prepareAgentExec(
     mode: flags.mode,
     serviceTier: flags.serviceTier,
     thinking: flags.thinking,
+    harness,
   };
 }
 
+/** The account's execution defaults, "" for anything undeclared. */
+interface AccountExecutionDefaults {
+  readonly harness: HarnessFlag;
+  readonly nativeModel: string;
+  readonly cursorModel: string;
+}
+
+const NO_ACCOUNT_DEFAULTS: AccountExecutionDefaults = { harness: "", nativeModel: "", cursorModel: "" };
+
 /**
- * Best-effort read of the caller's default model for native-harness runs
- * (CLI sessions are native — there is no --harness flag yet, so the cursor
- * default is deliberately not consulted). Any failure — network, auth, a
- * backend without IdentityAccount — resolves to "" and the run proceeds
- * exactly as an unfilled --model does today: a missing preference must
- * never fail a run.
+ * Best-effort read of the caller's execution defaults
+ * (`IdentityAccountPreferences.default_harness` / `default_*_model`) in one
+ * whoAmI round trip. Any failure — network, auth, a backend without
+ * IdentityAccount — resolves to no defaults and the run proceeds exactly as
+ * unfilled flags do today: a missing preference must never fail a run.
+ *
+ * The persisted harness value is allowlist-guarded to the shipped engines
+ * (the same guard the web launcher's useAccountExecutionDefaults applies):
+ * a client must not trust stored data it did not write, so anything outside
+ * native/cursor is treated as undeclared rather than stamped on the wire.
  */
-async function resolveModelFromAccountPreference(client: Stigmer): Promise<string> {
+async function resolveAccountExecutionDefaults(client: Stigmer): Promise<AccountExecutionDefaults> {
   try {
     const account = await client.identityAccount.whoAmI();
-    return account.spec?.preferences?.defaultNativeModel ?? "";
+    const prefs = account.spec?.preferences;
+    const declared = prefs?.defaultHarness;
+    return {
+      harness: declared === "native" || declared === "cursor" ? declared : "",
+      nativeModel: prefs?.defaultNativeModel ?? "",
+      cursorModel: prefs?.defaultCursorModel ?? "",
+    };
   } catch {
-    return "";
+    return NO_ACCOUNT_DEFAULTS;
   }
 }
 
@@ -227,3 +289,19 @@ export function validateThinking(mode: string): asserts mode is ThinkingFlag {
     );
   }
 }
+
+/**
+ * Validate the `--harness` flag. Empty means "use default": the account
+ * preference when the caller opted in, else the platform default (native).
+ * Only the shipped engines are accepted — other harness names that appear in
+ * UI metadata (copilot, codex, ...) have no proto mapping yet, so rejecting
+ * them here is honest, and this check catches spelling errors before a
+ * network round trip.
+ */
+export function validateHarness(harness: string): asserts harness is HarnessFlag {
+  if (harness !== "" && harness !== "native" && harness !== "cursor") {
+    throw new UsageError(
+      `invalid --harness value "${harness}": must be "native" or "cursor"`,
+    );
+  }
+}

package/src/resources/share.test.ts

@@ -12,7 +12,7 @@ import { classify, ExitCode, UsageError } from "../errors/index.js";
 import { shareAgent } from "./share.js";
 
 const CLOUD = { appOrigin: "https://app.stigmer.ai", isLocal: false };
-const LOCAL = { appOrigin: "http://localhost:8234", isLocal: true };
+const LOCAL = { appOrigin: "http://localhost:7234", isLocal: true };
 
 function makeAgent(): Agent {
   return create(AgentSchema, {
@@ -350,7 +350,7 @@ describe("shareAgent output", () => {
     const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...LOCAL });
 
     const link = result.sections.find((s) => s.title === "Public chat link");
-    expect(link?.items).toEqual(["http://localhost:8234/chat/acme/support-agent"]);
+    expect(link?.items).toEqual(["http://localhost:7234/chat/acme/support-agent"]);
     expect(result.hints.some((h) => h.includes("Stigmer Cloud"))).toBe(true);
   });