@xpert-ai/plugin-sdk 3.19.0 → 3.20.0

package/src/lib/agent/runtime/cli-model-profile.d.ts

@@ -0,0 +1,62 @@
+import type { ModelExecutionModel, ModelExecutionLimits, ModelExecutionProtocol, ModelFeature, CliPermissionMode } from '@xpert-ai/contracts';
+/** Configuration adapters describe secrets by reference; only the host materializes credentials. */
+export declare const CLI_MODEL_TOKEN_REFERENCE = "${XPERT_EXECUTION_TOKEN}";
+export interface CliModelConfiguration {
+    args: string[];
+    environment: Record<string, string>;
+    files: Array<{
+        name: string;
+        content: string;
+    }>;
+}
+export interface CliModelConfigurationInput {
+    directory: string;
+    gatewayBaseUrl: string;
+    defaultModelId?: string;
+    models: Array<Pick<ModelExecutionModel, 'id' | 'protocols' | 'contextWindow' | 'outputTokenLimit'>>;
+    /** @deprecated Legacy input only. Use the selected model's catalog metadata. */
+    limits?: Partial<ModelExecutionLimits> & {
+        maxOutputTokens?: number;
+    };
+    managed: boolean;
+    /** Host-resolved background approval policy; omitted preserves interactive/shell behavior. */
+    permissionMode?: CliPermissionMode;
+}
+/** Installed trusted code; neither an executable path nor a model permission comes from this adapter. */
+export interface CliModelProfile {
+    id: string;
+    revision: string;
+    command: string;
+    protocol: Extract<ModelExecutionProtocol, 'openai_chat' | 'openai_responses' | 'anthropic_messages'>;
+    requiredCapabilities: ModelFeature[];
+    /** Modes this profile explicitly implements; unsupported modes must not be silently ignored. */
+    permissionModes?: readonly CliPermissionMode[];
+    chatBridge?: {
+        versions: readonly string[];
+        requiredCapabilities: ModelFeature[];
+    };
+    /** Optional host-managed background transport. Arguments are trusted profile code, never model input. */
+    background?: {
+        versions: readonly string[];
+    } & ({
+        transport: 'opencode';
+    } | {
+        transport: 'jsonl';
+        args: readonly string[];
+        /** For CLIs without stdin prompt support. Host appends one literal argv value, never shell text. */
+        promptArgument?: string;
+    });
+    /** Exact complete argv sequences that never need a model grant. */
+    offlineArguments: readonly (readonly string[])[];
+    /** Exact accepted stdout values for a policy-pinned version probe. */
+    versionOutputs(version: string): string[];
+    configure(input: CliModelConfigurationInput): CliModelConfiguration;
+}
+export interface CliModelProfiles {
+    get(id: string): CliModelProfile | undefined;
+}
+export declare const CliModelProfilesCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<CliModelProfiles>;
+/** Additional execution sources can validate lifecycle without making OS depend on Pro entities. */
+export declare const ShellModelExecutionSourceCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<{
+    assertCurrent(context: import("@xpert-ai/contracts").ModelExecutionContext, preparing?: boolean): Promise<void>;
+}>;

package/src/lib/agent/runtime/dispatch.d.ts

@@ -0,0 +1,517 @@
+import { z } from 'zod/v3';
+export declare const agentRuntimeReplyTargetSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodOptional<z.ZodLiteral<"xpert">>;
+    xpertId: z.ZodString;
+    agentKey: z.ZodString;
+    conversationId: z.ZodString;
+    threadId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type?: "xpert";
+    threadId?: string;
+    conversationId?: string;
+    xpertId?: string;
+    agentKey?: string;
+}, {
+    type?: "xpert";
+    threadId?: string;
+    conversationId?: string;
+    xpertId?: string;
+    agentKey?: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"project_agent">;
+    projectId: z.ZodString;
+    agentKey: z.ZodLiteral<"general_agent">;
+    conversationId: z.ZodString;
+    threadId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type?: "project_agent";
+    threadId?: string;
+    conversationId?: string;
+    projectId?: string;
+    agentKey?: "general_agent";
+}, {
+    type?: "project_agent";
+    threadId?: string;
+    conversationId?: string;
+    projectId?: string;
+    agentKey?: "general_agent";
+}>]>;
+export type AgentRuntimeReplyTarget = z.output<typeof agentRuntimeReplyTargetSchema>;
+/** Persist with the immutable invocation request before launch. No credentials or arbitrary routing headers. */
+export declare const agentInvocationDispatchContextSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sourceMessageId: z.ZodString;
+    replyTo: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodOptional<z.ZodLiteral<"xpert">>;
+        xpertId: z.ZodString;
+        agentKey: z.ZodString;
+        conversationId: z.ZodString;
+        threadId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type?: "xpert";
+        threadId?: string;
+        conversationId?: string;
+        xpertId?: string;
+        agentKey?: string;
+    }, {
+        type?: "xpert";
+        threadId?: string;
+        conversationId?: string;
+        xpertId?: string;
+        agentKey?: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"project_agent">;
+        projectId: z.ZodString;
+        agentKey: z.ZodLiteral<"general_agent">;
+        conversationId: z.ZodString;
+        threadId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type?: "project_agent";
+        threadId?: string;
+        conversationId?: string;
+        projectId?: string;
+        agentKey?: "general_agent";
+    }, {
+        type?: "project_agent";
+        threadId?: string;
+        conversationId?: string;
+        projectId?: string;
+        agentKey?: "general_agent";
+    }>]>;
+    projectTask: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        projectId: z.ZodString;
+        projectTaskId: z.ZodString;
+        taskExecutionId: z.ZodString;
+    } & {
+        specification: z.ZodObject<{
+            digest: z.ZodString;
+            specification: z.ZodEffects<z.ZodObject<{
+                version: z.ZodLiteral<1>;
+                title: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+                requirements: z.ZodArray<z.ZodString, "many">;
+                steps: z.ZodArray<z.ZodObject<{
+                    stepIndex: z.ZodNumber;
+                    description: z.ZodString;
+                }, "strict", z.ZodTypeAny, {
+                    description?: string;
+                    stepIndex?: number;
+                }, {
+                    description?: string;
+                    stepIndex?: number;
+                }>, "many">;
+            }, "strict", z.ZodTypeAny, {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            }, {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            }>, {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            }, {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            }>;
+        }, "strict", z.ZodTypeAny, {
+            digest?: string;
+            specification?: {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            };
+        }, {
+            digest?: string;
+            specification?: {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            };
+        }>;
+        purpose: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+            type: z.ZodLiteral<"implementation">;
+        }, "strict", z.ZodTypeAny, {
+            type?: "implementation";
+        }, {
+            type?: "implementation";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"review">;
+            implementationExecutionId: z.ZodString;
+            implementationInvocationId: z.ZodString;
+            specificationDigest: z.ZodString;
+            evidence: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+                type: z.ZodLiteral<"artifact">;
+                artifactId: z.ZodString;
+                versionId: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                type?: "artifact";
+                versionId?: string;
+                artifactId?: string;
+            }, {
+                type?: "artifact";
+                versionId?: string;
+                artifactId?: string;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"invocation_result">;
+                invocationId: z.ZodString;
+                revision: z.ZodNumber;
+            }, "strict", z.ZodTypeAny, {
+                type?: "invocation_result";
+                revision?: number;
+                invocationId?: string;
+            }, {
+                type?: "invocation_result";
+                revision?: number;
+                invocationId?: string;
+            }>, z.ZodObject<{
+                type: z.ZodLiteral<"workspace_snapshot">;
+                snapshotId: z.ZodString;
+                digest: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                type?: "workspace_snapshot";
+                digest?: string;
+                snapshotId?: string;
+            }, {
+                type?: "workspace_snapshot";
+                digest?: string;
+                snapshotId?: string;
+            }>]>, "many">;
+        }, "strict", z.ZodTypeAny, {
+            type?: "review";
+            implementationExecutionId?: string;
+            implementationInvocationId?: string;
+            specificationDigest?: string;
+            evidence?: ({
+                type?: "artifact";
+                versionId?: string;
+                artifactId?: string;
+            } | {
+                type?: "invocation_result";
+                revision?: number;
+                invocationId?: string;
+            } | {
+                type?: "workspace_snapshot";
+                digest?: string;
+                snapshotId?: string;
+            })[];
+        }, {
+            type?: "review";
+            implementationExecutionId?: string;
+            implementationInvocationId?: string;
+            specificationDigest?: string;
+            evidence?: ({
+                type?: "artifact";
+                versionId?: string;
+                artifactId?: string;
+            } | {
+                type?: "invocation_result";
+                revision?: number;
+                invocationId?: string;
+            } | {
+                type?: "workspace_snapshot";
+                digest?: string;
+                snapshotId?: string;
+            })[];
+        }>]>;
+    }, "strict", z.ZodTypeAny, {
+        projectId?: string;
+        specification?: {
+            digest?: string;
+            specification?: {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            };
+        };
+        projectTaskId?: string;
+        taskExecutionId?: string;
+        purpose?: {
+            type?: "implementation";
+        } | {
+            type?: "review";
+            implementationExecutionId?: string;
+            implementationInvocationId?: string;
+            specificationDigest?: string;
+            evidence?: ({
+                type?: "artifact";
+                versionId?: string;
+                artifactId?: string;
+            } | {
+                type?: "invocation_result";
+                revision?: number;
+                invocationId?: string;
+            } | {
+                type?: "workspace_snapshot";
+                digest?: string;
+                snapshotId?: string;
+            })[];
+        };
+    }, {
+        projectId?: string;
+        specification?: {
+            digest?: string;
+            specification?: {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            };
+        };
+        projectTaskId?: string;
+        taskExecutionId?: string;
+        purpose?: {
+            type?: "implementation";
+        } | {
+            type?: "review";
+            implementationExecutionId?: string;
+            implementationInvocationId?: string;
+            specificationDigest?: string;
+            evidence?: ({
+                type?: "artifact";
+                versionId?: string;
+                artifactId?: string;
+            } | {
+                type?: "invocation_result";
+                revision?: number;
+                invocationId?: string;
+            } | {
+                type?: "workspace_snapshot";
+                digest?: string;
+                snapshotId?: string;
+            })[];
+        };
+    }>, {
+        projectId?: string;
+        specification?: {
+            digest?: string;
+            specification?: {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            };
+        };
+        projectTaskId?: string;
+        taskExecutionId?: string;
+        purpose?: {
+            type?: "implementation";
+        } | {
+            type?: "review";
+            implementationExecutionId?: string;
+            implementationInvocationId?: string;
+            specificationDigest?: string;
+            evidence?: ({
+                type?: "artifact";
+                versionId?: string;
+                artifactId?: string;
+            } | {
+                type?: "invocation_result";
+                revision?: number;
+                invocationId?: string;
+            } | {
+                type?: "workspace_snapshot";
+                digest?: string;
+                snapshotId?: string;
+            })[];
+        };
+    }, {
+        projectId?: string;
+        specification?: {
+            digest?: string;
+            specification?: {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            };
+        };
+        projectTaskId?: string;
+        taskExecutionId?: string;
+        purpose?: {
+            type?: "implementation";
+        } | {
+            type?: "review";
+            implementationExecutionId?: string;
+            implementationInvocationId?: string;
+            specificationDigest?: string;
+            evidence?: ({
+                type?: "artifact";
+                versionId?: string;
+                artifactId?: string;
+            } | {
+                type?: "invocation_result";
+                revision?: number;
+                invocationId?: string;
+            } | {
+                type?: "workspace_snapshot";
+                digest?: string;
+                snapshotId?: string;
+            })[];
+        };
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    version?: 1;
+    requestId?: string;
+    sourceMessageId?: string;
+    replyTo?: {
+        type?: "xpert";
+        threadId?: string;
+        conversationId?: string;
+        xpertId?: string;
+        agentKey?: string;
+    } | {
+        type?: "project_agent";
+        threadId?: string;
+        conversationId?: string;
+        projectId?: string;
+        agentKey?: "general_agent";
+    };
+    projectTask?: {
+        projectId?: string;
+        specification?: {
+            digest?: string;
+            specification?: {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            };
+        };
+        projectTaskId?: string;
+        taskExecutionId?: string;
+        purpose?: {
+            type?: "implementation";
+        } | {
+            type?: "review";
+            implementationExecutionId?: string;
+            implementationInvocationId?: string;
+            specificationDigest?: string;
+            evidence?: ({
+                type?: "artifact";
+                versionId?: string;
+                artifactId?: string;
+            } | {
+                type?: "invocation_result";
+                revision?: number;
+                invocationId?: string;
+            } | {
+                type?: "workspace_snapshot";
+                digest?: string;
+                snapshotId?: string;
+            })[];
+        };
+    };
+}, {
+    version?: 1;
+    requestId?: string;
+    sourceMessageId?: string;
+    replyTo?: {
+        type?: "xpert";
+        threadId?: string;
+        conversationId?: string;
+        xpertId?: string;
+        agentKey?: string;
+    } | {
+        type?: "project_agent";
+        threadId?: string;
+        conversationId?: string;
+        projectId?: string;
+        agentKey?: "general_agent";
+    };
+    projectTask?: {
+        projectId?: string;
+        specification?: {
+            digest?: string;
+            specification?: {
+                description?: string;
+                version?: 1;
+                title?: string;
+                steps?: {
+                    description?: string;
+                    stepIndex?: number;
+                }[];
+                requirements?: string[];
+            };
+        };
+        projectTaskId?: string;
+        taskExecutionId?: string;
+        purpose?: {
+            type?: "implementation";
+        } | {
+            type?: "review";
+            implementationExecutionId?: string;
+            implementationInvocationId?: string;
+            specificationDigest?: string;
+            evidence?: ({
+                type?: "artifact";
+                versionId?: string;
+                artifactId?: string;
+            } | {
+                type?: "invocation_result";
+                revision?: number;
+                invocationId?: string;
+            } | {
+                type?: "workspace_snapshot";
+                digest?: string;
+                snapshotId?: string;
+            })[];
+        };
+    };
+}>;
+export type AgentInvocationDispatchContext = z.output<typeof agentInvocationDispatchContextSchema>;

package/src/lib/agent/runtime/execution-runner.d.ts

@@ -0,0 +1,66 @@
+import type { CliPermissionMode, ModelExecutionEnvironment } from '@xpert-ai/contracts';
+import type { AgentInvocationScope, AgentInvocationResult, AgentJson } from './types';
+import type { AgentArtifactSelection } from './results';
+/** A host-managed process location. Remote service runtimes can use their own session/run handles. */
+export type AgentRunnerEnvironment = Extract<ModelExecutionEnvironment, {
+    type: 'computer' | 'sandbox';
+}>;
+/** A durable process receipt, not a second Agent task or a credential. Host methods must revalidate ownership. */
+interface AgentRunnerReceiptBase {
+    /** Owning platform invocation; never a caller-selected process launch key. */
+    invocationId: string;
+    /** Bound environment instance; replacing the instance invalidates this receipt. */
+    environment: AgentRunnerEnvironment;
+    /** Opaque host process reference, not necessarily an operating-system PID. */
+    processId: string;
+    /** Model execution grant ID only; never store its bearer secret in the receipt. */
+    grantId: string;
+    /** Actual business cwd selected by the host; retained verbatim for historical receipts. */
+    workingDirectory: string;
+    /** Tool selected from the approved binding and host policy, independent of the model provider. */
+    tool: {
+        id: string;
+        version: string;
+    };
+    /** Effective policy pinned when this process started; absent on historical receipts. */
+    permissionMode?: CliPermissionMode;
+}
+/** V1 retains its original cwd; V2 separates per-invocation records from the business cwd. */
+export type AgentRunnerReceipt = AgentRunnerReceiptBase & ({
+    version: 1;
+} | {
+    version: 2;
+    executionDirectory: string;
+});
+/** Per-scope host capability. Methods recheck the persisted invocation and receipt before side effects. */
+export interface AgentExecutionRunner {
+    /** Resolve the already persisted Invocation/Binding. Checkpoint before sending launch input. */
+    start(invocationId: string, checkpoint: (receipt: AgentRunnerReceipt) => Promise<void>): Promise<AgentRunnerReceipt>;
+    /** Observe the existing process. Unknown is not permission to relaunch or proof of completion. */
+    inspect(receipt: AgentRunnerReceipt): Promise<{
+        state: 'running' | 'exited' | 'unknown';
+        exitCode?: number;
+    }>;
+    /** Relative HTTP request over the approved local service transport; no caller-supplied URL or headers. */
+    request(receipt: AgentRunnerReceipt, request: {
+        method: 'GET' | 'POST';
+        path: string;
+        body?: AgentJson;
+        query?: {
+            limit: number;
+        };
+    }): Promise<unknown>;
+    /** Export only selected files after revalidating the persisted delivery request. No selection means no export. */
+    collectArtifacts(receipt: AgentRunnerReceipt, selection?: AgentArtifactSelection): Promise<NonNullable<AgentInvocationResult['artifacts']>>;
+    /** Revoke model access and request process termination. Only exited confirms termination. */
+    stop(receipt: AgentRunnerReceipt): Promise<{
+        state: 'exited' | 'stopping' | 'unknown';
+    }>;
+}
+export declare const AgentExecutionRunnerCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<AgentExecutionRunner>;
+export interface AgentExecutionRunnerFactory {
+    /** Capture trusted scope only; defer authorization and I/O to runner methods. Never launch during construction. */
+    createScopedRunner(scope: Readonly<AgentInvocationScope>): AgentExecutionRunner;
+}
+export declare const AgentExecutionRunnerFactoryCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<AgentExecutionRunnerFactory>;
+export {};

package/src/lib/agent/runtime/index.d.ts

@@ -1,3 +1,10 @@
 export * from './types';
 export * from './strategy';
 export * from './capability';
+export * from './model-execution';
+export * from './cli-model-profile';
+export * from './task-wait';
+export * from './results';
+export * from './execution-runner';
+export * from './dispatch';
+export * from './activity';

package/src/lib/agent/runtime/model-execution.d.ts

@@ -0,0 +1,15 @@
+import type { ModelExecutionContext } from '@xpert-ai/contracts';
+/** Trusted host adapter; bearer callers cannot validate their own execution environment. */
+export interface ModelExecutionEnvironmentGuard {
+    /** Check trusted runtime state and throw when the grant's bound environment is no longer valid. */
+    assertCurrent(context: Readonly<ModelExecutionContext>): Promise<void>;
+}
+/**
+ * Keeps shared OS model authorization independent of Pro Computer/Docker lifecycle details.
+ * Grant issuance, authentication, revalidation and renewal delegate environment checks to this host adapter.
+ * Implementations validate ownership and instance identity so a replaced runtime cannot keep its old grant.
+ * Execution validity is independent of desktop viewing sessions; managed runners may also require an operation lease.
+ * Other environments can supply their own checks without changing the grant service.
+ * This capability validates the bound environment; model selection and usage accounting remain separate concerns.
+ */
+export declare const ModelExecutionEnvironmentCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<ModelExecutionEnvironmentGuard>;