Add agent-guided execution and rollout controls for macros

ts/packages/agentServer/client/src/agentServerClient.ts

@@ -54,6 +54,7 @@ import {
     RunMacroRequest,
     RunMacroResponse,
     SearchMacrosRequest,
+    SubmitMacroCandidateRequest,
     TraceSummary,
     ValidateMacroRequest,
     getDispatcherChannelName,
@@ -160,6 +161,9 @@ export type AgentServerConnection = {
     disableMacro(request: DisableMacroRequest): Promise<MacroVersionRef>;
     deleteMacro(request: DeleteMacroRequest): Promise<void>;
     runMacro(request: RunMacroRequest): Promise<RunMacroResponse>;
+    submitMacroCandidate(
+        request: SubmitMacroCandidateRequest,
+    ): Promise<MacroVersionRef>;
     cancelMacroRun(runId: string): Promise<void>;
     getMacroRun(runId: string): Promise<MacroRunRecord>;
 
@@ -396,6 +400,12 @@ export function createAgentServerConnection(
             return rpc.invoke("runMacro", request);
         },
 
+        async submitMacroCandidate(
+            request: SubmitMacroCandidateRequest,
+        ): Promise<MacroVersionRef> {
+            return rpc.invoke("submitMacroCandidate", request);
+        },
+
         async cancelMacroRun(runId: string): Promise<void> {
             return rpc.invoke("cancelMacroRun", runId);
         },

ts/packages/agentServer/client/test/conversation-stubConnection.ts

@@ -160,6 +160,9 @@ export function makeStubConnection(
         async runMacro() {
             throw new Error("Not implemented by conversation test stub");
         },
+        async submitMacroCandidate() {
+            throw new Error("Not implemented by conversation test stub");
+        },
         async cancelMacroRun() {},
         async getMacroRun() {
             throw new Error("Not implemented by conversation test stub");

ts/packages/agentServer/protocol/src/index.ts

@@ -48,6 +48,7 @@ export {
     RunMacroRequest,
     RunMacroResponse,
     SearchMacrosRequest,
+    SubmitMacroCandidateRequest,
     TraceSummary,
     ValidateMacroRequest,
     getDispatcherChannelName,

ts/packages/agentServer/protocol/src/protocol.ts

@@ -27,6 +27,7 @@ import type {
     RunMacroRequest,
     RunMacroResponse,
     SearchMacrosRequest,
+    SubmitMacroCandidateRequest,
     TraceSummary,
     ValidateMacroRequest,
 } from "@typeagent/copilot-macros";
@@ -55,6 +56,7 @@ export type {
     RunMacroRequest,
     RunMacroResponse,
     SearchMacrosRequest,
+    SubmitMacroCandidateRequest,
     TraceSummary,
     ValidateMacroRequest,
 } from "@typeagent/copilot-macros";
@@ -213,6 +215,9 @@ export type AgentServerInvokeFunctions = {
     disableMacro: (request: DisableMacroRequest) => Promise<MacroVersionRef>;
     deleteMacro: (request: DeleteMacroRequest) => Promise<void>;
     runMacro: (request: RunMacroRequest) => Promise<RunMacroResponse>;
+    submitMacroCandidate: (
+        request: SubmitMacroCandidateRequest,
+    ) => Promise<MacroVersionRef>;
     cancelMacroRun: (runId: string) => Promise<void>;
     getMacroRun: (runId: string) => Promise<MacroRunRecord>;
 

ts/packages/agentServer/server/src/connectionHandler.ts

@@ -284,6 +284,8 @@ export function createAgentServerConnectionHandler(
             disableMacro: async (request) => macroManager.disableMacro(request),
             deleteMacro: async (request) => macroManager.deleteMacro(request),
             runMacro: async (request) => macroManager.runMacro(request),
+            submitMacroCandidate: async (request) =>
+                macroManager.submitMacroCandidate(request),
             cancelMacroRun: async (runId) => macroManager.cancelMacroRun(runId),
             getMacroRun: async (runId) => macroManager.getMacroRun(runId),
 

ts/packages/agentServer/server/test/macroRecordingRpc.spec.ts

@@ -124,7 +124,41 @@ describe("macro recording RPC", () => {
             status: "completed",
             macroId: approved.macroId,
         });
-
+        const approvedMacro = await connection.inspectMacro(approved);
+        await expect(
+            connection.runMacro({
+                runId: "agent-run-1",
+                macroId: approved.macroId,
+                version: approved.version,
+                preference: "agent",
+            }),
+        ).resolves.toMatchObject({
+            status: "agentRequired",
+            launch: {
+                agent: "typeagent-macro-runner",
+                candidate: { handoffRunId: "agent-run-1" },
+            },
+        });
+        const candidate = await connection.submitMacroCandidate({
+            sourceMacroId: approved.macroId,
+            sourceVersion: approved.version,
+            handoffRunId: "agent-run-1",
+            reason: "Adapted during agent-guided execution.",
+            inputs: approvedMacro.inputs,
+            steps: approvedMacro.steps,
+            executionEvidence: {
+                outcome: "completed",
+                toolCalls: 1,
+                retries: 0,
+                durationMs: 100,
+                tokensUsed: 100,
+                steps: [{ stepId: "step-1", status: "completed" }],
+            },
+        });
+        expect(candidate).toMatchObject({ version: 3, state: "draft" });
+        await expect(connection.inspectMacro(approved)).resolves.toMatchObject({
+            state: "approved",
+        });
         await connection.close();
     });
 });

ts/packages/agents/browserExtension/src/extension/serviceWorker/dispatcherConnection.ts

@@ -570,6 +570,7 @@ function makeConnectionAdapter(): AgentServerConnection {
         disableMacro: () => notSupported("disableMacro"),
         deleteMacro: () => notSupported("deleteMacro"),
         runMacro: () => notSupported("runMacro"),
+        submitMacroCandidate: () => notSupported("submitMacroCandidate"),
         cancelMacroRun: () => notSupported("cancelMacroRun"),
         getMacroRun: () => notSupported("getMacroRun"),
 

ts/packages/copilot-macros/src/contracts.ts

@@ -99,6 +99,15 @@ export interface CopilotToolMacro {
     sourceTraceId: string;
     createdAt: string;
     warnings: string[];
+    candidateProvenance?: MacroCandidateProvenance;
+}
+
+export interface MacroCandidateProvenance {
+    sourceMacroId: string;
+    sourceVersion: number;
+    handoffRunId: string;
+    reason: string;
+    submittedAt: string;
 }
 
 export interface MacroSummary {
@@ -199,6 +208,50 @@ export interface RunMacroRequest extends InspectMacroRequest {
     dryRun?: boolean;
 }
 
+export interface AgentRunnerLaunchPayload {
+    agent: "typeagent-macro-runner";
+    macro: CopilotToolMacro;
+    inputs: Record<string, unknown>;
+    reason: {
+        code: "agentRequested" | "agentRequired";
+        message: string;
+        stepIds: string[];
+    };
+    budgets: {
+        maxToolCalls: number;
+        maxRetries: number;
+        timeoutMs: number;
+        maxTokens: number;
+    };
+    candidate: {
+        sourceMacroId: string;
+        sourceVersion: number;
+        handoffRunId: string;
+    };
+}
+
+export interface SubmitMacroCandidateRequest {
+    sourceMacroId: string;
+    sourceVersion: number;
+    handoffRunId: string;
+    reason: string;
+    name?: string;
+    description?: string;
+    inputs: MacroInput[];
+    steps: MacroStep[];
+    executionEvidence: {
+        outcome: "completed";
+        toolCalls: number;
+        retries: number;
+        durationMs: number;
+        tokensUsed: number;
+        steps: Array<{
+            stepId: string;
+            status: "completed" | "failed" | "denied" | "cancelled";
+        }>;
+    };
+}
+
 export interface MacroRunStep {
     stepId: string;
     toolName: string;
@@ -239,6 +292,7 @@ export type RunMacroResponse =
           macroId: string;
           version: number;
           reason: string;
+          launch: AgentRunnerLaunchPayload;
       };
 
 export interface ReplayToolDescriptor {