@xenosystem/agent-sdk 0.9.22 → 0.9.25

package/dist/automation/index.d.cts

@@ -1,3 +1,4 @@
+import { WebJobProgress } from "@xenosystem/web-context-client/progress";
 declare const XENO_ARTIFACT_SCHEMA_VERSION: 1;
 type XenoJsonPrimitive = string | number | boolean | null;
 type XenoJsonValue = XenoJsonPrimitive | XenoJsonObject | XenoJsonValue[];
@@ -327,6 +328,30 @@ interface XenoArtifactListQuery {
     sensitivity?: XenoArtifactSensitivity[];
     includeSuperseded?: boolean;
 }
+interface PromptSectionContext {
+    readonly systemPrompt: string;
+    readonly taskPrompt?: string;
+    readonly iteration: number;
+    readonly model: string;
+}
+interface PromptSectionProvider {
+    name: string;
+    order?: number;
+    provide(ctx: PromptSectionContext): string | null | undefined;
+}
+type PermissionProfileName = "default" | "read-only" | "trusted-dev";
+interface AgentToolPolicy {
+    mode?: "inherit" | "none" | "readOnly" | "default" | "fullAccess";
+    allow?: string[];
+    deny?: string[];
+}
+type AgentDefinitionIsolation = "none" | "worktree";
+declare const XENO_AGENT_PROFILE_SCHEMA_VERSION: 2;
+type AgentProfileKind = "primary" | "subagent" | "service";
+type AgentProfileCollaborationMode = "chat" | "plan" | "execute" | "review";
+type AgentProfileMemoryScope = "none" | "session" | "project" | "user";
+type AgentProfileSoulMode = "disabled" | "read" | "learn";
+type AgentProfileIsolation = AgentDefinitionIsolation | "container";
 declare const AGENT_PROFILE_EXTERNAL_ACTIONS: readonly [
     "publish",
     "deploy",
@@ -339,6 +364,82 @@ declare const AGENT_PROFILE_EXTERNAL_ACTIONS: readonly [
 ];
 type AgentProfileExternalAction = (typeof AGENT_PROFILE_EXTERNAL_ACTIONS)[number];
 type AgentProfileActionDecision = "allow" | "ask" | "deny";
+type AgentProfileEvidenceKind = "sources" | "file-references" | "tests" | "typecheck" | "build" | "diff" | "deployment-proof" | "human-review";
+interface AgentProfileSkillPolicy {
+    preload: string[];
+    allow?: string[];
+    deny: string[];
+}
+interface AgentProfileExternalActionPolicy {
+    default: AgentProfileActionDecision;
+    overrides?: Partial<Record<AgentProfileExternalAction, AgentProfileActionDecision>>;
+    requireCurrentTurnApproval: AgentProfileExternalAction[];
+}
+interface AgentProfileCapabilities {
+    tools: AgentToolPolicy;
+    skills: AgentProfileSkillPolicy;
+    hooks: string[];
+    mcpServers?: string[];
+    delegatedAgents?: string[];
+    permissionProfile: PermissionProfileName;
+    externalActions: AgentProfileExternalActionPolicy;
+}
+interface AgentProfileMemoryPolicy {
+    scope: AgentProfileMemoryScope;
+    role: string;
+    soul: AgentProfileSoulMode;
+}
+interface AgentProfileExecutionPolicy {
+    defaultMode: AgentProfileCollaborationMode;
+    allowedModes: AgentProfileCollaborationMode[];
+    isolation: AgentProfileIsolation;
+    allowBackground: boolean;
+    planForComplexTasks: boolean;
+    defaultDryRun: boolean;
+    maxTurns?: number;
+}
+interface AgentProfileCompletionPolicy {
+    evidence: AgentProfileEvidenceKind[];
+    requirePrimarySources: boolean;
+    requireCurrentInformation: boolean;
+    requireHumanReview: boolean;
+    stopConditions: string[];
+}
+interface AgentProfilePresentation {
+    label: string;
+    color: string;
+    glyph: string;
+}
+interface AgentProfileV2 {
+    schemaVersion: typeof XENO_AGENT_PROFILE_SCHEMA_VERSION;
+    id: string;
+    version: string;
+    displayName: string;
+    description: string;
+    kind: AgentProfileKind;
+    prompt: string;
+    model?: {
+        preferred?: string;
+        effort?: "low" | "medium" | "high";
+    };
+    capabilities: AgentProfileCapabilities;
+    memory: AgentProfileMemoryPolicy;
+    execution: AgentProfileExecutionPolicy;
+    completion: AgentProfileCompletionPolicy;
+    presentation: AgentProfilePresentation;
+    tags: string[];
+}
+interface CompiledAgentProfile {
+    schemaVersion: typeof XENO_AGENT_PROFILE_SCHEMA_VERSION;
+    profile: AgentProfileV2;
+    fingerprint: string;
+    boundarySources: string[];
+    capabilities: AgentProfileCapabilities;
+    memory: AgentProfileMemoryPolicy;
+    execution: AgentProfileExecutionPolicy;
+    completion: AgentProfileCompletionPolicy;
+    promptSection: PromptSectionProvider;
+}
 declare const XENO_CAPABILITY_LEASE_SCHEMA_VERSION: 1;
 type XenoCapabilityKind = "filesystem-read" | "filesystem-write" | "process-execute" | "network-connect" | "secret-use" | "external-action" | "browser-read" | "browser-act" | "computer-observe" | "computer-act" | "tool-invoke" | `custom:${string}`;
 type XenoCapabilityEffect = "read" | "write" | "execute" | "external";
@@ -432,6 +533,7 @@ interface WebContextToolResult {
         mediaType: string;
         bytes: number;
     };
+    jobProgress?: WebJobProgress;
 }
 interface ToolDefinition {
     name: string;
@@ -513,6 +615,7 @@ interface ToolProgressUpdate {
     bytes?: number;
     outputBytes?: number;
     nextOffset?: number;
+    webContextProgress?: WebJobProgress;
 }
 interface ToolAuthorizationReceipt {
     turnId: string;
@@ -567,8 +670,41 @@ interface TextBlock {
     type: "text";
     text: string;
 }
+interface AgentCapabilities {
+    terminal: boolean;
+    fileRead: boolean;
+    fileWrite: boolean;
+    appLaunch: boolean;
+}
 type ExecutionSecurityLevel = "policy-only" | "process-hardened" | "contained";
 type ExecutionTrustMode = "trusted-workspace" | "untrusted";
+interface ContainmentCertificationBinding {
+    manifestPath: string;
+    candidateSha256: string;
+    expectedCertificationId?: string;
+    trustedPublicKeys: Record<string, string>;
+}
+interface PolicyEnforcerConfig {
+    allowedDirectories: string[];
+    workingDirectory?: string;
+    capabilities: AgentCapabilities;
+    executionLevel?: ExecutionSecurityLevel;
+    trustMode?: ExecutionTrustMode;
+    requireOsContainment?: boolean;
+    allowNetwork?: boolean;
+    containmentCertification?: ContainmentCertificationBinding;
+    deniedDirectories?: string[];
+    containedEnvironmentAllowlist?: string[];
+    temporaryDirectories?: string[];
+    workspace?: {
+        id: string;
+        name: string;
+    };
+    team?: {
+        id: string;
+        name: string;
+    };
+}
 interface ExecutionSecurityCapabilities {
     policyEnforcement: boolean;
     restrictedIdentity: boolean;
@@ -579,6 +715,24 @@ interface ExecutionSecurityCapabilities {
     inheritedHandleAllowlist: boolean;
     environmentSanitization: boolean;
 }
+interface ProcessContainmentStatus {
+    available: boolean;
+    requestedLevel: ExecutionSecurityLevel;
+    effectiveLevel: ExecutionSecurityLevel | "unavailable";
+    adapter: "policy-enforcer" | "windows-restricted-token-job" | "linux-bubblewrap" | "microsoft-mxc" | "unavailable";
+    isolation: "policy-only" | "process-hardening" | "filesystem-network" | "none";
+    certified: boolean;
+    capabilities: ExecutionSecurityCapabilities;
+    limitations: string[];
+    reason: string;
+    adapterVersion?: string;
+    backend?: string;
+    isolationTier?: string;
+    nativeBinarySha256?: string;
+    certificationArtifactId?: string;
+    certificationManifestSha256?: string;
+    needsHostPreparation?: boolean;
+}
 declare const XENO_SECURE_EXECUTION_CONTRACT_SCHEMA_VERSION: 1;
 type XenoExecutionEnforcement = "none" | "policy" | "os";
 interface XenoExecutionIdentity {
@@ -974,6 +1128,91 @@ declare class XenoLoopbackAutomationAdapter implements XenoAutomationAdapter {
     stop(operationId: string, reason: string): Promise<void>;
     private request;
 }
+declare const XENO_BROWSER_CONTROL_PLANE_OPERATIONS: readonly [
+    "browser.navigate",
+    "browser.back",
+    "browser.forward",
+    "browser.reload",
+    "browser.wait",
+    "browser.snapshot",
+    "browser.screenshot",
+    "browser.locate",
+    "browser.tabs.list",
+    "browser.tabs.open",
+    "browser.console.read",
+    "browser.network.read",
+    "browser.storage.read",
+    "browser.page-errors.read",
+    "browser.click",
+    "browser.type",
+    "browser.key",
+    "browser.select",
+    "browser.scroll",
+    "browser.tabs.close",
+    "browser.upload",
+    "browser.download"
+];
+interface XenoBrowserControlPlaneAdapterOptions {
+    baseUrl: string;
+    token: string;
+    driver: "browser" | "extension";
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+declare class XenoBrowserControlPlaneAdapter implements XenoAutomationAdapter {
+    private readonly options;
+    private readonly base;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(options: XenoBrowserControlPlaneAdapterOptions);
+    manifest(): Promise<XenoAutomationAdapterManifest>;
+    preflight(request: XenoAutomationRequest, signal: AbortSignal): Promise<XenoAutomationPreflight>;
+    execute(request: XenoAutomationRequest, preflight: XenoAutomationPreflight, _grant: XenoAutomationExecutionGrant, signal: AbortSignal): Promise<XenoAutomationAdapterExecutionResult>;
+    stop(_operationId: string, _reason: string): Promise<void>;
+    private resultEvidence;
+    private snapshotEvidence;
+    private call;
+}
+interface ToolRegistryOptions {
+    validateInputs?: boolean;
+    toolSchemaMode?: "all" | "demand";
+}
+declare class ToolRegistry {
+    private tools;
+    private compiledSchemas;
+    private changeListeners;
+    private aliasNames;
+    private validateInputs;
+    private readonly toolSchemaMode;
+    private readonly activatedDefinitions;
+    constructor(options?: ToolRegistryOptions);
+    setValidateInputs(enabled: boolean): this;
+    get inputValidationEnabled(): boolean;
+    get schemaLoadingMode(): "all" | "demand";
+    register(tool: RegisteredTool): void;
+    registerAlias(tool: RegisteredTool): void;
+    registerAll(tools: Iterable<RegisteredTool>): void;
+    unregister(name: string): boolean;
+    onChange(listener: () => void): () => void;
+    private emitChange;
+    get(name: string): RegisteredTool | undefined;
+    getDefinitions(): ToolDefinition[];
+    getDefinitionsForRequest(): ToolDefinition[];
+    getCapabilityCatalog(): string;
+    activateMatchingDefinitions(query: string, limit?: number): ToolDefinition[];
+    private static namespaceOf;
+    getDefinitionsByNamespace(namespace: string): ToolDefinition[];
+    listNamespaces(): string[];
+    execute(name: string, input: Record<string, unknown>, context?: ToolExecutionContext): Promise<ToolResult>;
+    listNames(): string[];
+    has(name: string): boolean;
+    projectPolicyInput(name: string, input: Record<string, unknown>): ToolPolicyProjection | {
+        error: ToolResult;
+    };
+    get size(): number;
+    private compileDefinition;
+    private assertDefinitionsExportable;
+}
 interface XenoGovernedAutomationToolExecution {
     operation: XenoAutomationOperation;
     governingToolName: string;
@@ -994,4 +1233,106 @@ interface CreateXenoGovernedAutomationToolsOptions {
     operations?: readonly XenoAutomationOperation[];
 }
 declare function createXenoGovernedAutomationTools(options: CreateXenoGovernedAutomationToolsOptions): RegisteredTool[];
-export { type CreateXenoGovernedAutomationToolsOptions, type MaterializeXenoAutomationEvidenceOptions, XENO_AUTOMATION_OPERATIONS, XENO_AUTOMATION_PROTOCOL_VERSION, type XenoAutomationAdapter, type XenoAutomationAdapterExecutionResult, type XenoAutomationAdapterManifest, type XenoAutomationConformanceCheck, type XenoAutomationConformanceReport, type XenoAutomationEffect, XenoAutomationError, type XenoAutomationErrorCode, type XenoAutomationEvidenceContent, type XenoAutomationEvidenceInput, type XenoAutomationEvidencePhase, type XenoAutomationEvidencePolicy, type XenoAutomationExecutionGrant, type XenoAutomationExecutionResult, type XenoAutomationIdentity, type XenoAutomationLeaseAuthority, type XenoAutomationOperation, type XenoAutomationOperationDescriptor, type XenoAutomationPreflight, type XenoAutomationRequest, type XenoAutomationSurface, type XenoAutomationTarget, type XenoBrowserAutomationOperation, type XenoComputerAutomationOperation, XenoGovernedAutomationExecutor, type XenoGovernedAutomationExecutorOptions, type XenoGovernedAutomationToolExecution, type XenoGovernedAutomationToolRuntime, XenoLoopbackAutomationAdapter, type XenoLoopbackAutomationAdapterOptions, assertRequiredXenoAutomationEvidence, assertValidXenoAutomationAdapterManifest, assertValidXenoAutomationRequest, assertXenoAutomationAdapterConformant, assertXenoAutomationAuthority, buildXenoAutomationCapabilityUse, createXenoAutomationConformanceReport, createXenoGovernedAutomationTools, describeXenoAutomationOperation, isXenoAutomationOperation, materializeXenoAutomationEvidence, persistXenoAutomationEvidence, resolveXenoAutomationEvidencePolicy };
+interface CliAutomationAuditEvent {
+    eventType: "automation_lease_approved" | "automation_completed" | "automation_failed";
+    traceId: string;
+    operation: XenoAutomationOperation;
+    operationId: string;
+    leaseId?: string;
+    contractFingerprint?: string;
+    status?: string;
+    artifactIds?: string[];
+    permissionReason?: string;
+}
+interface CliAutomationAuditLoggerPort {
+    append(event: {
+        trace_id: string;
+        event_type: string;
+        actor: "system";
+        risk_level: "low" | "high";
+        decision?: "allow";
+        status: "ok" | "error";
+        reason?: string;
+        metadata: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+interface CliAutomationEnvironment {
+    browser?: {
+        driver: "browser" | "extension";
+        baseUrl?: string;
+        token?: string;
+        readDomains: string[];
+        actDomains: string[];
+        deniedDomains: string[];
+        ports: number[];
+        allowLoopbackDevelopment: boolean;
+        uploads: "deny" | "prompt" | "allow";
+        downloads: "deny" | "prompt" | "allow";
+        recording: "disabled" | "bounded";
+    };
+    computer?: {
+        baseUrl?: string;
+        token?: string;
+        deviceId?: string;
+        allowedApplications: string[];
+    };
+}
+interface CliAutomationSurfaceStatus {
+    surface: "browser" | "computer";
+    configured: boolean;
+    available: boolean;
+    certified: boolean;
+    adapterId?: string;
+    adapterVersion?: string;
+    operations: string[];
+    limitations: string[];
+    error?: string;
+}
+interface CliAutomationStatusReport {
+    schemaVersion: 1;
+    protocolVersion: 1;
+    enabled: boolean;
+    surfaces: CliAutomationSurfaceStatus[];
+    docs: string;
+}
+interface CreateCliGovernedAutomationRuntimeOptions {
+    cwd: () => string;
+    profile: () => CompiledAgentProfile;
+    runId: string;
+    agentId?: string;
+    sessionId?: string;
+    workspaceId?: string;
+    surface: "cli" | "hub" | "ide" | "api" | "hosted";
+    securityPolicy?: () => PolicyEnforcerConfig | undefined;
+    securityStatus?: ProcessContainmentStatus;
+    safeMode?: boolean;
+    environment?: CliAutomationEnvironment;
+    onAudit?: (event: CliAutomationAuditEvent) => Promise<void> | void;
+}
+declare class CliGovernedAutomationRuntime implements XenoGovernedAutomationToolRuntime {
+    private readonly options;
+    private readonly leases;
+    private readonly activeExecutors;
+    private readonly environment;
+    private browserAdapter?;
+    private computerAdapter?;
+    constructor(options: CreateCliGovernedAutomationRuntimeOptions);
+    register(registry: ToolRegistry): number;
+    execute(input: XenoGovernedAutomationToolExecution): Promise<XenoAutomationExecutionResult>;
+    stop(operationId: string, reason?: string): Promise<boolean>;
+    private securityPolicy;
+    private adapterFor;
+    private audit;
+}
+declare function createCliGovernedAutomationRuntime(options: CreateCliGovernedAutomationRuntimeOptions): CliGovernedAutomationRuntime;
+declare function createCliAutomationAuditSink(logger: CliAutomationAuditLoggerPort | undefined): ((event: CliAutomationAuditEvent) => Promise<void>) | undefined;
+declare function inspectCliAutomationStatus(environment?: CliAutomationEnvironment): Promise<CliAutomationStatusReport>;
+declare function readCliAutomationEnvironment(env?: NodeJS.ProcessEnv): CliAutomationEnvironment;
+declare function renderCliAutomationStatus(report: CliAutomationStatusReport): string;
+type XenoHostAutomationAuditEvent = CliAutomationAuditEvent;
+type XenoHostAutomationAuditLoggerPort = CliAutomationAuditLoggerPort;
+type XenoHostAutomationEnvironment = CliAutomationEnvironment;
+type XenoHostAutomationSurfaceStatus = CliAutomationSurfaceStatus;
+type XenoHostAutomationStatusReport = CliAutomationStatusReport;
+type CreateXenoHostGovernedAutomationRuntimeOptions = CreateCliGovernedAutomationRuntimeOptions;
+export { type CliAutomationAuditEvent, type CliAutomationAuditLoggerPort, type CliAutomationEnvironment, type CliAutomationStatusReport, type CliAutomationSurfaceStatus, CliGovernedAutomationRuntime, type CreateCliGovernedAutomationRuntimeOptions, type CreateXenoGovernedAutomationToolsOptions, type CreateXenoHostGovernedAutomationRuntimeOptions, type MaterializeXenoAutomationEvidenceOptions, XENO_AUTOMATION_OPERATIONS, XENO_AUTOMATION_PROTOCOL_VERSION, XENO_BROWSER_CONTROL_PLANE_OPERATIONS, type XenoAutomationAdapter, type XenoAutomationAdapterExecutionResult, type XenoAutomationAdapterManifest, type XenoAutomationConformanceCheck, type XenoAutomationConformanceReport, type XenoAutomationEffect, XenoAutomationError, type XenoAutomationErrorCode, type XenoAutomationEvidenceContent, type XenoAutomationEvidenceInput, type XenoAutomationEvidencePhase, type XenoAutomationEvidencePolicy, type XenoAutomationExecutionGrant, type XenoAutomationExecutionResult, type XenoAutomationIdentity, type XenoAutomationLeaseAuthority, type XenoAutomationOperation, type XenoAutomationOperationDescriptor, type XenoAutomationPreflight, type XenoAutomationRequest, type XenoAutomationSurface, type XenoAutomationTarget, type XenoBrowserAutomationOperation, XenoBrowserControlPlaneAdapter, type XenoBrowserControlPlaneAdapterOptions, type XenoComputerAutomationOperation, XenoGovernedAutomationExecutor, type XenoGovernedAutomationExecutorOptions, type XenoGovernedAutomationToolExecution, type XenoGovernedAutomationToolRuntime, type XenoHostAutomationAuditEvent, type XenoHostAutomationAuditLoggerPort, type XenoHostAutomationEnvironment, type XenoHostAutomationStatusReport, type XenoHostAutomationSurfaceStatus, CliGovernedAutomationRuntime as XenoHostGovernedAutomationRuntime, XenoLoopbackAutomationAdapter, type XenoLoopbackAutomationAdapterOptions, assertRequiredXenoAutomationEvidence, assertValidXenoAutomationAdapterManifest, assertValidXenoAutomationRequest, assertXenoAutomationAdapterConformant, assertXenoAutomationAuthority, buildXenoAutomationCapabilityUse, createCliAutomationAuditSink, createCliGovernedAutomationRuntime, createXenoAutomationConformanceReport, createXenoGovernedAutomationTools, createCliAutomationAuditSink as createXenoHostAutomationAuditSink, createCliGovernedAutomationRuntime as createXenoHostGovernedAutomationRuntime, describeXenoAutomationOperation, inspectCliAutomationStatus, inspectCliAutomationStatus as inspectXenoHostAutomationStatus, isXenoAutomationOperation, materializeXenoAutomationEvidence, persistXenoAutomationEvidence, readCliAutomationEnvironment, readCliAutomationEnvironment as readXenoHostAutomationEnvironment, renderCliAutomationStatus, renderCliAutomationStatus as renderXenoHostAutomationStatus, resolveXenoAutomationEvidencePolicy };