@testchimp/cli 0.1.22 → 0.1.23

package/dist/cli/program.js

@@ -44,6 +44,41 @@ function mergeBodies(flagBody, jsonInputRaw) {
         return flagBody;
     return deepMerge(flagBody, extra);
 }
+/** Shared agent policy/traceability flags for mutating CRUD commands. */
+function addAgentTraceabilityOptions(cmd) {
+    return cmd
+        .option("--workflow-id <id>", "Catalog workflow id for agent Activity")
+        .option("--workflow-execution-id <ulid>", "Stable ULID for the whole agent run")
+        .option("--policy-file <name>", "Policy filename (e.g. run-qa.policy.md)")
+        .option("--policy-version <semver>", "Policy version from frontmatter")
+        .option("--git-sha <sha>", "Git SHA (defaults to HEAD)")
+        .option("--actor-type <type>", "LOCAL_AGENT | CLOUD_AGENT")
+        .option("--user-id <id>", "Optional user id")
+        .option("--branch-name <name>", "Git branch name")
+        .option("--agent-model <model>", "Optional agent model id (agent/CLI only)");
+}
+function collectAgentTraceabilityFlags(opts) {
+    const body = {};
+    if (opts.workflowId)
+        body.workflowId = String(opts.workflowId).trim();
+    if (opts.workflowExecutionId)
+        body.workflowExecutionId = String(opts.workflowExecutionId).trim();
+    if (opts.policyFile)
+        body.policyFile = String(opts.policyFile).trim();
+    if (opts.policyVersion)
+        body.policyVersion = String(opts.policyVersion).trim();
+    if (opts.gitSha)
+        body.gitSha = String(opts.gitSha).trim();
+    if (opts.actorType)
+        body.actorType = String(opts.actorType).trim();
+    if (opts.userId)
+        body.userId = String(opts.userId).trim();
+    if (opts.branchName)
+        body.branchName = String(opts.branchName).trim();
+    if (opts.agentModel)
+        body.agentModel = String(opts.agentModel).trim();
+    return body;
+}
 function stderrProgress(msg) {
     console.error(`[testchimp] ${msg}`);
 }
@@ -176,48 +211,50 @@ export function buildCliProgram() {
         const out = await runTool("fetch-execution-report", merged, { postMcp });
         console.log(out);
     });
-    program
+    addAgentTraceabilityOptions(program
         .command("create-user-story")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "create-user-story").description)
         .addOption(jsonInputOption())
         .requiredOption("--platform-file-path <path>")
-        .requiredOption("--title <title>")
-        .action(async (opts) => {
-        const body = { platformFilePath: opts.platformFilePath, title: opts.title };
+        .requiredOption("--title <title>")).action(async (opts) => {
+        const body = {
+            platformFilePath: opts.platformFilePath,
+            title: opts.title,
+            ...collectAgentTraceabilityFlags(opts),
+        };
         const merged = mergeBodies(body, opts.jsonInput);
         const out = await runTool("create-user-story", merged, { postMcp });
         console.log(out);
     });
-    program
+    addAgentTraceabilityOptions(program
         .command("create-test-scenario")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "create-test-scenario").description)
         .addOption(jsonInputOption())
         .requiredOption("--platform-file-path <path>")
         .requiredOption("--title <title>")
-        .requiredOption("--user-story-ordinal-id <n>")
-        .action(async (opts) => {
+        .requiredOption("--user-story-ordinal-id <n>")).action(async (opts) => {
         const body = {
             platformFilePath: opts.platformFilePath,
             title: opts.title,
             userStoryOrdinalId: Number(opts.userStoryOrdinalId),
+            ...collectAgentTraceabilityFlags(opts),
         };
         const merged = mergeBodies(body, opts.jsonInput);
         const out = await runTool("create-test-scenario", merged, { postMcp });
         console.log(out);
     });
-    program
+    addAgentTraceabilityOptions(program
         .command("update-user-story")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "update-user-story").description)
         .addOption(jsonInputOption())
         .option("--content <markdown>", "full markdown including frontmatter")
-        .option("--content-file <path>", "read markdown from file")
-        .action(async (opts) => {
+        .option("--content-file <path>", "read markdown from file")).action(async (opts) => {
         let content = opts.content;
         if (opts.contentFile)
             content = await readFile(String(opts.contentFile), "utf8");
         if (!content)
             throw new Error("Provide --content or --content-file (or full body via --json-input)");
-        const body = { content };
+        const body = { content, ...collectAgentTraceabilityFlags(opts) };
         const merged = mergeBodies(body, opts.jsonInput);
         const out = await runTool("update-user-story", merged, { postMcp });
         console.log(out);
@@ -286,15 +323,16 @@ export function buildCliProgram() {
         const out = await runTool("get-issue-details", { issueId: String(merged.issueId).trim() }, { postMcp });
         console.log(out);
     });
-    program
+    addAgentTraceabilityOptions(program
         .command("update-issue-status")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "update-issue-status").description)
         .addOption(jsonInputOption())
         .option("--issue-id <id>", "Issue ordinal id (#B-123, B-123, B123, or 123)")
         .option("--status <status>", "ACTIVE | IGNORED | FIXED | DUPLICATE | IN_PROGRESS_BUG | ARCHIVED_BUG | BLOCKED")
-        .option("--ignore-reason <reason>", "When status=IGNORED: INTENDED_BEHAVIOUR | INACCURATE_ASSESSMENT | NOT_IMPORTANT")
-        .action(async (opts) => {
-        const body = {};
+        .option("--ignore-reason <reason>", "When status=IGNORED: INTENDED_BEHAVIOUR | INACCURATE_ASSESSMENT | NOT_IMPORTANT")).action(async (opts) => {
+        const body = {
+            ...collectAgentTraceabilityFlags(opts),
+        };
         if (opts.issueId)
             body.issueId = String(opts.issueId).trim();
         if (opts.status)
@@ -308,16 +346,10 @@ export function buildCliProgram() {
         if (!merged.status || String(merged.status).trim() === "") {
             throw new Error("status is required (ACTIVE | IGNORED | FIXED | DUPLICATE | IN_PROGRESS_BUG | ARCHIVED_BUG | BLOCKED)");
         }
-        const out = await runTool("update-issue-status", {
-            issueId: String(merged.issueId).trim(),
-            status: String(merged.status).trim(),
-            ...(merged.ignoreReason
-                ? { ignoreReason: String(merged.ignoreReason).trim() }
-                : {}),
-        }, { postMcp });
+        const out = await runTool("update-issue-status", merged, { postMcp });
         console.log(out);
     });
-    program
+    addAgentTraceabilityOptions(program
         .command("create-issue")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "create-issue").description)
         .addOption(jsonInputOption())
@@ -332,9 +364,10 @@ export function buildCliProgram() {
         .option("--assignee <userId>", "Assignee user id")
         .option("--labels <csv>", "Comma-separated labels")
         .option("--source <name>", "External ingest source identifier (stored as label source:<name>)")
-        .option("--environment <name>", "Environment tag (defaults to QA when omitted)")
-        .action(async (opts) => {
-        const body = {};
+        .option("--environment <name>", "Environment tag (defaults to QA when omitted)")).action(async (opts) => {
+        const body = {
+            ...collectAgentTraceabilityFlags(opts),
+        };
         if (opts.title)
             body.title = String(opts.title).trim();
         if (opts.description)
@@ -427,19 +460,18 @@ export function buildCliProgram() {
         }, { postMcp });
         console.log(out);
     });
-    program
+    addAgentTraceabilityOptions(program
         .command("update-test-scenario")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "update-test-scenario").description)
         .addOption(jsonInputOption())
         .option("--content <markdown>")
-        .option("--content-file <path>")
-        .action(async (opts) => {
+        .option("--content-file <path>")).action(async (opts) => {
         let content = opts.content;
         if (opts.contentFile)
             content = await readFile(String(opts.contentFile), "utf8");
         if (!content)
             throw new Error("Provide --content or --content-file (or full body via --json-input)");
-        const body = { content };
+        const body = { content, ...collectAgentTraceabilityFlags(opts) };
         const merged = mergeBodies(body, opts.jsonInput);
         const out = await runTool("update-test-scenario", merged, { postMcp });
         console.log(out);
@@ -945,6 +977,7 @@ export function buildCliProgram() {
         .option("--actor-type <type>", "LOCAL_AGENT|CLOUD_AGENT (or local-agent|cloud-agent)")
         .option("--user-id <id>", "Optional user id for traceability")
         .option("--branch-name <name>", "Git branch")
+        .option("--agent-model <model>", "Optional agent model id (agent/CLI only)")
         .requiredOption("--entity-type <type>", "USER_STORY|SCENARIO|SMART_TEST|POLICY|ISSUE|TEST_EXECUTION|TEST_INVOCATION_BATCH|EXPLORATION|EVENT|WORKFLOW")
         .option("--entity-identity <ordinal>", "Project-scoped ordinal id (mutually exclusive with --test-json)")
         .option("--test-json <json>", "TestLocator JSON (folderPath/fileName/testSuite/testName)")
@@ -968,6 +1001,8 @@ export function buildCliProgram() {
             body.userId = String(opts.userId);
         if (opts.branchName)
             body.branchName = String(opts.branchName);
+        if (opts.agentModel)
+            body.agentModel = String(opts.agentModel).trim();
         if (opts.entityIdentity)
             body.entityIdentity = String(opts.entityIdentity);
         if (opts.testJson)

package/dist/core/agentTraceability.d.ts

@@ -0,0 +1,22 @@
+/** Flat CLI/MCP fields that map to AgentActionTraceability. */
+export type AgentTraceabilityFields = {
+    workflowId?: string;
+    workflowExecutionId?: string;
+    policyFile?: string;
+    policyVersion?: string;
+    gitSha?: string;
+    actorType?: string;
+    userId?: string;
+    branchName?: string;
+    agentModel?: string;
+    /** Nested form (wins over flat when both present and non-empty). */
+    agentTraceability?: Record<string, unknown>;
+};
+/**
+ * Build camelCase AgentActionTraceability for MCP JSON bodies.
+ * Returns undefined unless the caller supplied explicit traceability intent
+ * **and** a non-empty workflowId (server requires workflow_id for inline Activity).
+ * Auto-fills gitSha / agentModel / userId only after that bar is met.
+ * Non-empty nested `agentTraceability` wins over flat for overlapping keys.
+ */
+export declare function buildAgentTraceabilityPayload(a: AgentTraceabilityFields): Record<string, unknown> | undefined;

package/dist/core/agentTraceability.js

@@ -0,0 +1,95 @@
+import { resolveGitHeadSha } from "./gitSha.js";
+function nonEmptyString(v) {
+    if (v == null)
+        return undefined;
+    const s = String(v).trim();
+    return s === "" ? undefined : s;
+}
+function hasExplicitTraceabilityIntent(a) {
+    if (nonEmptyString(a.workflowId))
+        return true;
+    if (nonEmptyString(a.workflowExecutionId))
+        return true;
+    if (nonEmptyString(a.policyFile))
+        return true;
+    if (nonEmptyString(a.policyVersion))
+        return true;
+    if (nonEmptyString(a.gitSha))
+        return true;
+    if (nonEmptyString(a.actorType))
+        return true;
+    if (nonEmptyString(a.userId))
+        return true;
+    if (nonEmptyString(a.branchName))
+        return true;
+    if (nonEmptyString(a.agentModel))
+        return true;
+    if (a.agentTraceability && typeof a.agentTraceability === "object") {
+        return Object.keys(a.agentTraceability).some((k) => nonEmptyString(a.agentTraceability[k]) != null);
+    }
+    return false;
+}
+function normalizeActorType(raw) {
+    if (raw == null)
+        return undefined;
+    const s = String(raw).toUpperCase().replace(/-/g, "_");
+    if (s === "CLOUD_AGENT")
+        return "CLOUD_AGENT";
+    if (s === "LOCAL_AGENT")
+        return "LOCAL_AGENT";
+    return undefined;
+}
+/**
+ * Build camelCase AgentActionTraceability for MCP JSON bodies.
+ * Returns undefined unless the caller supplied explicit traceability intent
+ * **and** a non-empty workflowId (server requires workflow_id for inline Activity).
+ * Auto-fills gitSha / agentModel / userId only after that bar is met.
+ * Non-empty nested `agentTraceability` wins over flat for overlapping keys.
+ */
+export function buildAgentTraceabilityPayload(a) {
+    if (!hasExplicitTraceabilityIntent(a)) {
+        return undefined;
+    }
+    const nested = a.agentTraceability &&
+        typeof a.agentTraceability === "object" &&
+        Object.keys(a.agentTraceability).some((k) => nonEmptyString(a.agentTraceability[k]) != null)
+        ? { ...a.agentTraceability }
+        : null;
+    const out = {};
+    const workflowId = nonEmptyString(nested?.workflowId) ?? nonEmptyString(a.workflowId);
+    const workflowExecutionId = nonEmptyString(nested?.workflowExecutionId) ?? nonEmptyString(a.workflowExecutionId);
+    const policyFile = nonEmptyString(nested?.policyFile) ?? nonEmptyString(a.policyFile);
+    const policyVersion = nonEmptyString(nested?.policyVersion) ?? nonEmptyString(a.policyVersion);
+    const gitShaExplicit = nonEmptyString(nested?.gitSha) ?? nonEmptyString(a.gitSha);
+    const actorType = normalizeActorType(nested?.actorType) ?? normalizeActorType(a.actorType);
+    const userId = nonEmptyString(nested?.userId) ??
+        nonEmptyString(a.userId) ??
+        nonEmptyString(process.env.TESTCHIMP_USER_ID);
+    const branchName = nonEmptyString(nested?.branchName) ?? nonEmptyString(a.branchName);
+    const agentModel = nonEmptyString(nested?.agentModel) ??
+        nonEmptyString(a.agentModel) ??
+        nonEmptyString(process.env.TESTCHIMP_AGENT_MODEL);
+    // Server requires workflow_id for inline mutation Activity — do not send orphan payloads.
+    if (!workflowId) {
+        return undefined;
+    }
+    out.workflowId = workflowId;
+    if (workflowExecutionId)
+        out.workflowExecutionId = workflowExecutionId;
+    if (policyFile)
+        out.policyFile = policyFile;
+    if (policyVersion)
+        out.policyVersion = policyVersion;
+    const gitSha = resolveGitHeadSha(gitShaExplicit);
+    if (gitSha)
+        out.gitSha = gitSha;
+    if (actorType)
+        out.actorType = actorType;
+    if (userId)
+        out.userId = userId;
+    if (branchName)
+        out.branchName = branchName;
+    if (agentModel)
+        out.agentModel = agentModel;
+    return out;
+}

package/dist/core/schemas.d.ts

@@ -54,17 +54,163 @@ export declare const fetchExecutionReportInput: z.ZodObject<{
     batchInvocationId: z.ZodOptional<z.ZodString>;
     jobId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const agentActorTypeSchema: z.ZodEnum<{
+    LOCAL_AGENT: "LOCAL_AGENT";
+    CLOUD_AGENT: "CLOUD_AGENT";
+    "local-agent": "local-agent";
+    "cloud-agent": "cloud-agent";
+}>;
+/** Nested AgentActionTraceability (agent_traceability.proto) for mutating MCP CRUDs. */
+export declare const agentActionTraceabilitySchema: z.ZodObject<{
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Flat + nested traceability fields shared by create/update MCP tools. */
+export declare const agentTraceabilityFieldsSchema: z.ZodObject<{
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
 export declare const createUserStoryInput: z.ZodObject<{
     platformFilePath: z.ZodString;
     title: z.ZodString;
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const createTestScenarioInput: z.ZodObject<{
     platformFilePath: z.ZodString;
     title: z.ZodString;
     userStoryOrdinalId: z.ZodCoercedNumber<unknown>;
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const updatePlanMarkdownInput: z.ZodObject<{
     content: z.ZodString;
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const markPlanItemsImplementationDoneInput: z.ZodObject<{
     scenarioOrdinalIds: z.ZodOptional<z.ZodArray<z.ZodCoercedNumber<unknown>>>;
@@ -103,6 +249,36 @@ export declare const updateIssueStatusInput: z.ZodObject<{
         INACCURATE_ASSESSMENT: "INACCURATE_ASSESSMENT";
         NOT_IMPORTANT: "NOT_IMPORTANT";
     }>>;
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const createIssueInput: z.ZodObject<{
     title: z.ZodString;
@@ -169,6 +345,36 @@ export declare const createIssueInput: z.ZodObject<{
     environment: z.ZodOptional<z.ZodString>;
     attachments: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     artifactReference: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const emptyInput: z.ZodObject<{}, z.core.$strip>;
 export declare const getBranchSpecificEndpointConfigInput: z.ZodObject<{
@@ -735,8 +941,8 @@ export declare const requirementFindingUserStateSchema: z.ZodEnum<{
 }>;
 /** RequirementQualityReportSource — proto enum names. */
 export declare const requirementQualityReportSourceSchema: z.ZodEnum<{
-    CLOUD: "CLOUD";
     LOCAL_AGENT: "LOCAL_AGENT";
+    CLOUD: "CLOUD";
 }>;
 /** SuggestedFixKind — proto enum names. */
 export declare const suggestedFixKindSchema: z.ZodEnum<{
@@ -864,8 +1070,8 @@ export declare const requirementQualityReportSchema: z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     source: z.ZodOptional<z.ZodEnum<{
-        CLOUD: "CLOUD";
         LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD: "CLOUD";
     }>>;
     metrics: z.ZodOptional<z.ZodObject<{
         overall: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
@@ -949,8 +1155,8 @@ export declare const reportRequirementQualityFindingsInput: z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         source: z.ZodOptional<z.ZodEnum<{
-            CLOUD: "CLOUD";
             LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD: "CLOUD";
         }>>;
         metrics: z.ZodOptional<z.ZodObject<{
             overall: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
@@ -1020,12 +1226,6 @@ export declare const reportRequirementQualityFindingsInput: z.ZodObject<{
     subjectEntityId: z.ZodOptional<z.ZodString>;
     ordinalId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
-export declare const agentActorTypeSchema: z.ZodEnum<{
-    LOCAL_AGENT: "LOCAL_AGENT";
-    CLOUD_AGENT: "CLOUD_AGENT";
-    "local-agent": "local-agent";
-    "cloud-agent": "cloud-agent";
-}>;
 /** Closed vocabulary for report-agent-action entity_type (agent_workflow.proto AgentActionEntityType). */
 export declare const agentActionEntityTypeSchema: z.ZodEnum<{
     SMART_TEST: "SMART_TEST";
@@ -1071,6 +1271,23 @@ export declare const reportAgentActionInput: z.ZodObject<{
     }>>;
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    traceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     entityType: z.ZodEnum<{
         SMART_TEST: "SMART_TEST";
         SCENARIO: "SCENARIO";

package/dist/core/schemas.js

@@ -53,18 +53,46 @@ export const fetchExecutionReportInput = z
         });
     }
 });
+export const agentActorTypeSchema = z.enum(["LOCAL_AGENT", "CLOUD_AGENT", "local-agent", "cloud-agent"]);
+/** Nested AgentActionTraceability (agent_traceability.proto) for mutating MCP CRUDs. */
+export const agentActionTraceabilitySchema = z
+    .object({
+    workflowId: z.string().optional(),
+    workflowExecutionId: z.string().optional(),
+    policyFile: z.string().optional(),
+    policyVersion: z.string().optional(),
+    gitSha: z.string().optional(),
+    actorType: agentActorTypeSchema.optional(),
+    userId: z.string().optional(),
+    branchName: z.string().optional(),
+    agentModel: z.string().optional(),
+})
+    .strict();
+/** Flat + nested traceability fields shared by create/update MCP tools. */
+export const agentTraceabilityFieldsSchema = z.object({
+    workflowId: z.string().optional(),
+    workflowExecutionId: z.string().optional(),
+    policyFile: z.string().optional(),
+    policyVersion: z.string().optional(),
+    gitSha: z.string().optional(),
+    actorType: agentActorTypeSchema.optional(),
+    userId: z.string().optional(),
+    branchName: z.string().optional(),
+    agentModel: z.string().optional(),
+    agentTraceability: agentActionTraceabilitySchema.optional(),
+});
 export const createUserStoryInput = z.object({
     platformFilePath: z.string().min(1),
     title: z.string().min(1),
-});
+}).merge(agentTraceabilityFieldsSchema);
 export const createTestScenarioInput = z.object({
     platformFilePath: z.string().min(1),
     title: z.string().min(1),
     userStoryOrdinalId: z.coerce.number().int().positive(),
-});
+}).merge(agentTraceabilityFieldsSchema);
 export const updatePlanMarkdownInput = z.object({
     content: z.string().min(1),
-});
+}).merge(agentTraceabilityFieldsSchema);
 export const markPlanItemsImplementationDoneInput = z.object({
     scenarioOrdinalIds: z.array(z.coerce.number().int().positive()).optional(),
     userStoryOrdinalIds: z.array(z.coerce.number().int().positive()).optional(),
@@ -105,7 +133,7 @@ export const updateIssueStatusInput = z.object({
     ignoreReason: z
         .enum(["INTENDED_BEHAVIOUR", "INACCURATE_ASSESSMENT", "NOT_IMPORTANT"])
         .optional(),
-});
+}).merge(agentTraceabilityFieldsSchema);
 const linkedEntityTypeSchema = z.enum([
     "STORY",
     "SCENARIO",
@@ -171,7 +199,7 @@ export const createIssueInput = z.object({
     environment: z.string().optional(),
     attachments: z.array(z.record(z.string(), z.unknown())).optional(),
     artifactReference: z.record(z.string(), z.unknown()).optional(),
-});
+}).merge(agentTraceabilityFieldsSchema);
 export const emptyInput = z.object({});
 export const getBranchSpecificEndpointConfigInput = z.object({
     branchName: z.string().optional(),
@@ -507,7 +535,6 @@ export const reportRequirementQualityFindingsInput = z
         });
     }
 });
-export const agentActorTypeSchema = z.enum(["LOCAL_AGENT", "CLOUD_AGENT", "local-agent", "cloud-agent"]);
 /** Closed vocabulary for report-agent-action entity_type (agent_workflow.proto AgentActionEntityType). */
 export const agentActionEntityTypeSchema = z.enum([
     "USER_STORY",
@@ -549,6 +576,8 @@ export const reportAgentActionInput = z
     actorType: agentActorTypeSchema.optional(),
     userId: z.string().optional(),
     branchName: z.string().optional(),
+    agentModel: z.string().optional(),
+    traceability: agentActionTraceabilitySchema.optional(),
     entityType: agentActionEntityTypeSchema,
     /** Project-scoped ordinal id (or explicitly provided execution/batch id). Mutually exclusive with `test`. */
     entityIdentity: z.string().optional(),

package/dist/core/tools.js

@@ -2,6 +2,7 @@ import { normalizeScope } from "./normalize.js";
 import { runProvisionEphemeralEnvironmentAndWait } from "./ephemeralWait.js";
 import * as S from "./schemas.js";
 import { resolveGitHeadSha } from "./gitSha.js";
+import { buildAgentTraceabilityPayload } from "./agentTraceability.js";
 function platformToProtoEnum(platform) {
     switch (platform) {
         case "ios":
@@ -167,14 +168,20 @@ export const TOOL_DEFINITIONS = [
             "Response includes content: canonical stub markdown already containing id: US-<ordinalId>. " +
             "BLOCKING workflow: call this FIRST → Write the returned content to the repo plans/stories path " +
             "(edit body as needed but keep id:) → call update-user-story with the full markdown. " +
-            "Never write story markdown that omits id. platformFilePath must be under plans/stories/ and end with .md.",
+            "Never write story markdown that omits id. platformFilePath must be under plans/stories/ and end with .md. " +
+            "Optional agentTraceability (or flat workflowId/workflowExecutionId/policyFile/policyVersion/gitSha/…) " +
+            "records AGENT_WORKFLOW_ACTIVITY inline — no separate report-agent-action needed for this create.",
         inputSchema: S.createUserStoryInput,
         execute: async (args, { postMcp }) => {
             const a = args;
-            return postMcp("/api/mcp/create_user_story", {
+            const body = {
                 platformFilePath: a.platformFilePath,
                 title: a.title,
-            });
+            };
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
+            return postMcp("/api/mcp/create_user_story", body);
         },
     },
     {
@@ -185,37 +192,52 @@ export const TOOL_DEFINITIONS = [
             "(edit body as needed but keep id: and story:) → call update-test-scenario with the full markdown. " +
             "Never write scenario markdown that omits id. update-test-scenario rejects missing id/story with a clear error. " +
             "platformFilePath must be under plans/scenarios/ and end with .md. " +
-            "userStoryOrdinalId is the numeric part of the parent US-<n> id.",
+            "userStoryOrdinalId is the numeric part of the parent US-<n> id. " +
+            "Optional agentTraceability records Activity inline (no separate report-agent-action for this create).",
         inputSchema: S.createTestScenarioInput,
         execute: async (args, { postMcp }) => {
             const a = args;
-            return postMcp("/api/mcp/create_test_scenario", {
+            const body = {
                 platformFilePath: a.platformFilePath,
                 title: a.title,
                 userStoryOrdinalId: a.userStoryOrdinalId,
-            });
+            };
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
+            return postMcp("/api/mcp/create_test_scenario", body);
         },
     },
     {
         kebab: "update-user-story",
         description: "Sync a user story markdown file to the platform after local edits. " +
             "Requires frontmatter id: US-<n> (platform-issued). Missing id returns an error telling you to call create-user-story first. " +
-            "Parses frontmatter (id, title, priority) and updates the linked support file and entity.",
+            "Parses frontmatter (id, title, priority) and updates the linked support file and entity. " +
+            "Optional agentTraceability records UPDATED Activity inline.",
         inputSchema: S.updatePlanMarkdownInput,
         execute: async (args, { postMcp }) => {
             const a = args;
-            return postMcp("/api/mcp/update_user_story", { content: a.content });
+            const body = { content: a.content };
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
+            return postMcp("/api/mcp/update_user_story", body);
         },
     },
     {
         kebab: "update-test-scenario",
         description: "Sync a test scenario markdown file to the platform after local edits. " +
             "Requires frontmatter id: TS-<n> and story: US-<n>. Missing either returns an error telling you to call create-test-scenario first. " +
-            "Parses frontmatter and updates linking if story changes.",
+            "Parses frontmatter and updates linking if story changes. " +
+            "Optional agentTraceability records UPDATED Activity inline.",
         inputSchema: S.updatePlanMarkdownInput,
         execute: async (args, { postMcp }) => {
             const a = args;
-            return postMcp("/api/mcp/update_test_scenario", { content: a.content });
+            const body = { content: a.content };
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
+            return postMcp("/api/mcp/update_test_scenario", body);
         },
     },
     {
@@ -275,7 +297,8 @@ export const TOOL_DEFINITIONS = [
         description: "Update a TestChimp issue status by ordinal id (same flexible issueId formats as get-issue-details). " +
             "status must be one of: ACTIVE, IGNORED, FIXED, DUPLICATE, IN_PROGRESS_BUG, ARCHIVED_BUG, BLOCKED. " +
             "For /testchimp fix issue: set IN_PROGRESS_BUG after applying a code fix; set FIXED only after user confirmation / commits pushed. " +
-            "Optional ignoreReason when status is IGNORED: INTENDED_BEHAVIOUR | INACCURATE_ASSESSMENT | NOT_IMPORTANT.",
+            "Optional ignoreReason when status is IGNORED: INTENDED_BEHAVIOUR | INACCURATE_ASSESSMENT | NOT_IMPORTANT. " +
+            "Optional agentTraceability records UPDATED Activity inline.",
         inputSchema: S.updateIssueStatusInput,
         execute: async (args, { postMcp }) => {
             const a = args;
@@ -285,6 +308,9 @@ export const TOOL_DEFINITIONS = [
             };
             if (a.ignoreReason)
                 body.ignoreReason = a.ignoreReason;
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
             return postMcp("/api/mcp/update_issue_status", body);
         },
     },
@@ -294,6 +320,8 @@ export const TOOL_DEFINITIONS = [
             "Use simple fields for common creates, or pass the full curated contract via --json-input " +
             "(description, issueType, category, severity, status, reportedReleaseId, dueDateMillis, assignee, " +
             "linkTargets, labels, source, environment, attachments, artifactReference). " +
+            "Optional agentTraceability (or flat workflowId/policyFile/…) records CREATED Activity inline — " +
+            "prefer this over a separate report-agent-action for issue creates. " +
             "Authenticated via project API key; project is resolved from the key.",
         inputSchema: S.createIssueInput,
         execute: async (args, { postMcp }) => {
@@ -327,6 +355,9 @@ export const TOOL_DEFINITIONS = [
                 body.attachments = a.attachments;
             if (a.artifactReference != null)
                 body.artifactReference = a.artifactReference;
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
             return postMcp("/api/mcp/create_issue", body);
         },
     },
@@ -837,6 +868,27 @@ export const TOOL_DEFINITIONS = [
                 body.userId = process.env.TESTCHIMP_USER_ID;
             if (a.branchName)
                 body.branchName = a.branchName;
+            // Nested traceability wins for agentModel; only fill from flat/env when nested omits it.
+            if (a.traceability && typeof a.traceability === "object") {
+                const nested = { ...a.traceability };
+                const nestedModel = nested.agentModel != null && String(nested.agentModel).trim() !== ""
+                    ? String(nested.agentModel).trim()
+                    : undefined;
+                const flatModel = a.agentModel?.trim() || process.env.TESTCHIMP_AGENT_MODEL?.trim();
+                if (nestedModel) {
+                    nested.agentModel = nestedModel;
+                }
+                else if (flatModel) {
+                    nested.agentModel = flatModel;
+                }
+                body.traceability = nested;
+            }
+            else {
+                const model = a.agentModel?.trim() || process.env.TESTCHIMP_AGENT_MODEL?.trim();
+                if (model) {
+                    body.traceability = { agentModel: model };
+                }
+            }
             if (a.test) {
                 body.test = a.test;
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@testchimp/cli",
-  "version": "0.1.22",
-  "description": "TestChimp CLI and MCP server — coverage, plans, EaaS, TrueCoverage (calls /api/mcp/*)",
+  "version": "0.1.23",
+  "description": "TestChimp CLI and MCP server \u2014 coverage, plans, EaaS, TrueCoverage (calls /api/mcp/*)",
   "type": "module",
   "main": "dist/bin/testchimp.js",
   "types": "dist/bin/testchimp.d.ts",