@crewx/sdk 0.9.0-rc.160 → 0.9.0-rc.162

package/dist/agent-interceptor/chain.d.ts

@@ -0,0 +1,25 @@
+import { type ModelProviderFactory } from './model-runner';
+import { type AgentInterceptorItem, type InterceptorLaneRun, type InterceptorPhase } from './types';
+export interface InterceptorRunContext {
+    cwd: string;
+    agentId: string;
+    traceId: string;
+    threadId?: string;
+    model?: string;
+    signal?: AbortSignal;
+    onSpawn?: (pid: number) => void;
+    onExit?: () => void;
+    providerFactory?: ModelProviderFactory;
+}
+export declare class AgentInterceptorChain {
+    readonly items: readonly AgentInterceptorItem[];
+    private constructor();
+    static fromAgent(agent: {
+        id: string;
+        interceptors?: unknown;
+    }): AgentInterceptorChain | undefined;
+    hasPhase(phase: InterceptorPhase): boolean;
+    get responseIntercepted(): boolean;
+    run(phase: InterceptorPhase, text: string, ctx: InterceptorRunContext): Promise<InterceptorLaneRun>;
+    private invoke;
+}

package/dist/agent-interceptor/index.d.ts

@@ -0,0 +1,6 @@
+export { AgentInterceptorChain, type InterceptorRunContext } from './chain';
+export { AgentInterceptorConfigError, AgentInterceptorItemSchema, AgentInterceptorChainSchema, AGENT_INTERCEPTOR_SCHEMA_VERSION, parseAgentInterceptorItems, } from './schema';
+export { runProgramInterceptor, buildProgramInterceptorEnv } from './program-runner';
+export { runModelInterceptor, buildModelInterceptorSystemPrompt, type ModelProviderFactory } from './model-runner';
+export { RPC_CODE } from './protocol';
+export { INTERCEPTOR_BLOCKED, INTERCEPTOR_CONFIG_INVALID, INTERCEPTOR_FAILED, INTERCEPTOR_STOPPED, type AgentInterceptorItem, type InterceptorInvocation, type InterceptorLaneRun, type InterceptorMode, type InterceptorOutcome, type InterceptorPhase, type InterceptorSeverity, type InterceptorStepLog, type InterceptorType, type InterceptorUsage, type InterceptorVerdict, } from './types';

package/dist/agent-interceptor/model-runner.d.ts

@@ -0,0 +1,19 @@
+import { type ProviderRuntime } from '../provider/bridge';
+import type { InterceptorInvocation, InterceptorType } from './types';
+export type ModelProviderFactory = (providerStr: string) => ProviderRuntime;
+export interface ModelInterceptorInvocation {
+    providerStr: string;
+    model?: string;
+    instruction: string;
+    type: InterceptorType;
+    role: string;
+    text: string;
+    timeoutMs: number;
+    cwd: string;
+    signal?: AbortSignal;
+    onSpawn?: (pid: number) => void;
+    onExit?: () => void;
+    providerFactory?: ModelProviderFactory;
+}
+export declare function buildModelInterceptorSystemPrompt(type: InterceptorType, instruction: string): string;
+export declare function runModelInterceptor(input: ModelInterceptorInvocation): Promise<InterceptorInvocation>;

package/dist/agent-interceptor/program-runner.d.ts

@@ -0,0 +1,13 @@
+import { type InterceptorInvokeRequest } from './protocol';
+import type { InterceptorInvocation } from './types';
+export declare function buildProgramInterceptorEnv(source?: NodeJS.ProcessEnv): Record<string, string>;
+export interface ProgramInterceptorInvocation {
+    command: readonly string[];
+    cwd: string;
+    request: InterceptorInvokeRequest;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    onSpawn?: (pid: number) => void;
+    onExit?: () => void;
+}
+export declare function runProgramInterceptor(input: ProgramInterceptorInvocation): Promise<InterceptorInvocation>;

package/dist/agent-interceptor/protocol.d.ts

@@ -0,0 +1,68 @@
+import type { InterceptorMessage, InterceptorVerdict } from './types';
+export declare const INTERCEPTOR_RPC_METHOD = "interceptor/invoke";
+export declare const INTERCEPTOR_RPC_EVENT = "crewx/agent.run";
+export declare const INTERCEPTOR_RPC_ID = 1;
+export declare const INTERCEPTOR_STDOUT_MAX_BYTES: number;
+export declare const RPC_CODE: {
+    readonly TIMEOUT: -32000;
+    readonly EXIT_FAILURE: -32001;
+    readonly MALFORMED_OUTPUT: -32002;
+    readonly OUTPUT_TOO_LARGE: -32003;
+    readonly SPAWN_FAILED: -32004;
+    readonly ABORTED: -32005;
+    readonly PAYLOAD_INVALID: -32006;
+    readonly PROVIDER_FAILED: -32007;
+};
+export interface InterceptorInvokeRequest {
+    jsonrpc: '2.0';
+    id: number;
+    method: typeof INTERCEPTOR_RPC_METHOD;
+    params: {
+        name: string;
+        event: typeof INTERCEPTOR_RPC_EVENT;
+        phase: 'request' | 'response';
+        payload: {
+            messages: InterceptorMessage[];
+            model: string | null;
+        };
+        config: Record<string, unknown>;
+        timeoutMs: number;
+        context: {
+            sessionId: string;
+            traceId: string;
+            agentId: string;
+        };
+    };
+}
+export declare function buildInvokeRequest(input: {
+    name: string;
+    phase: 'request' | 'response';
+    messages: InterceptorMessage[];
+    model: string | null;
+    config: Record<string, unknown>;
+    timeoutMs: number;
+    sessionId: string;
+    traceId: string;
+    agentId: string;
+}): InterceptorInvokeRequest;
+export type RpcFailure = {
+    ok: false;
+    code: number;
+    message: string;
+};
+export type RpcParse = {
+    ok: true;
+    result: unknown;
+} | RpcFailure;
+export declare function parseSingleRpcResponse(stdout: string, id: number): RpcParse;
+export type MutationInterpretation = {
+    ok: true;
+    modified: boolean;
+    messages: InterceptorMessage[];
+} | RpcFailure;
+export declare function interpretMutationResult(result: unknown, input: InterceptorMessage[]): MutationInterpretation;
+export type ValidationInterpretation = {
+    ok: true;
+    verdict: InterceptorVerdict;
+} | RpcFailure;
+export declare function interpretValidationResult(result: unknown): ValidationInterpretation;

package/dist/agent-interceptor/run-stop.d.ts

@@ -0,0 +1,3 @@
+export declare function registerInterceptorRunStop(taskId: string, controller: AbortController): void;
+export declare function releaseInterceptorRunStop(taskId: string, controller: AbortController): void;
+export declare function requestInterceptorRunStop(taskId: string): boolean;

package/dist/agent-interceptor/schema.d.ts

@@ -0,0 +1,267 @@
+import { z } from 'zod';
+import { type AgentInterceptorItem } from './types';
+export declare const AGENT_INTERCEPTOR_SCHEMA_VERSION = 1;
+export declare const AGENT_INTERCEPTOR_DEFAULT_TIMEOUT_MS = 10000;
+export declare const AGENT_INTERCEPTOR_MAX_TIMEOUT_MS = 120000;
+export declare const AgentInterceptorItemSchema: z.ZodEffects<z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<["mutation", "validation"]>;
+    phase: z.ZodEnum<["request", "response"]>;
+    mode: z.ZodDefault<z.ZodEnum<["active", "audit"]>>;
+    failOpen: z.ZodDefault<z.ZodBoolean>;
+    priorityHint: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    command: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    model: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodOptional<z.ZodString>;
+        instruction: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        provider: string;
+        instruction: string;
+        model?: string | undefined;
+    }, {
+        provider: string;
+        instruction: string;
+        model?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    mode: "active" | "audit";
+    type: "mutation" | "validation";
+    config: Record<string, unknown>;
+    enabled: boolean;
+    timeoutMs: number;
+    phase: "request" | "response";
+    failOpen: boolean;
+    priorityHint: number;
+    model?: {
+        provider: string;
+        instruction: string;
+        model?: string | undefined;
+    } | undefined;
+    command?: string[] | undefined;
+}, {
+    name: string;
+    type: "mutation" | "validation";
+    phase: "request" | "response";
+    mode?: "active" | "audit" | undefined;
+    model?: {
+        provider: string;
+        instruction: string;
+        model?: string | undefined;
+    } | undefined;
+    command?: string[] | undefined;
+    config?: Record<string, unknown> | undefined;
+    enabled?: boolean | undefined;
+    timeoutMs?: number | undefined;
+    failOpen?: boolean | undefined;
+    priorityHint?: number | undefined;
+}>, {
+    name: string;
+    mode: "active" | "audit";
+    type: "mutation" | "validation";
+    config: Record<string, unknown>;
+    enabled: boolean;
+    timeoutMs: number;
+    phase: "request" | "response";
+    failOpen: boolean;
+    priorityHint: number;
+    model?: {
+        provider: string;
+        instruction: string;
+        model?: string | undefined;
+    } | undefined;
+    command?: string[] | undefined;
+}, {
+    name: string;
+    type: "mutation" | "validation";
+    phase: "request" | "response";
+    mode?: "active" | "audit" | undefined;
+    model?: {
+        provider: string;
+        instruction: string;
+        model?: string | undefined;
+    } | undefined;
+    command?: string[] | undefined;
+    config?: Record<string, unknown> | undefined;
+    enabled?: boolean | undefined;
+    timeoutMs?: number | undefined;
+    failOpen?: boolean | undefined;
+    priorityHint?: number | undefined;
+}>;
+export declare const AgentInterceptorChainSchema: z.ZodEffects<z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    items: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<["mutation", "validation"]>;
+        phase: z.ZodEnum<["request", "response"]>;
+        mode: z.ZodDefault<z.ZodEnum<["active", "audit"]>>;
+        failOpen: z.ZodDefault<z.ZodBoolean>;
+        priorityHint: z.ZodDefault<z.ZodNumber>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        command: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        model: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodOptional<z.ZodString>;
+            instruction: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            provider: string;
+            instruction: string;
+            model?: string | undefined;
+        }, {
+            provider: string;
+            instruction: string;
+            model?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        mode: "active" | "audit";
+        type: "mutation" | "validation";
+        config: Record<string, unknown>;
+        enabled: boolean;
+        timeoutMs: number;
+        phase: "request" | "response";
+        failOpen: boolean;
+        priorityHint: number;
+        model?: {
+            provider: string;
+            instruction: string;
+            model?: string | undefined;
+        } | undefined;
+        command?: string[] | undefined;
+    }, {
+        name: string;
+        type: "mutation" | "validation";
+        phase: "request" | "response";
+        mode?: "active" | "audit" | undefined;
+        model?: {
+            provider: string;
+            instruction: string;
+            model?: string | undefined;
+        } | undefined;
+        command?: string[] | undefined;
+        config?: Record<string, unknown> | undefined;
+        enabled?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        failOpen?: boolean | undefined;
+        priorityHint?: number | undefined;
+    }>, {
+        name: string;
+        mode: "active" | "audit";
+        type: "mutation" | "validation";
+        config: Record<string, unknown>;
+        enabled: boolean;
+        timeoutMs: number;
+        phase: "request" | "response";
+        failOpen: boolean;
+        priorityHint: number;
+        model?: {
+            provider: string;
+            instruction: string;
+            model?: string | undefined;
+        } | undefined;
+        command?: string[] | undefined;
+    }, {
+        name: string;
+        type: "mutation" | "validation";
+        phase: "request" | "response";
+        mode?: "active" | "audit" | undefined;
+        model?: {
+            provider: string;
+            instruction: string;
+            model?: string | undefined;
+        } | undefined;
+        command?: string[] | undefined;
+        config?: Record<string, unknown> | undefined;
+        enabled?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        failOpen?: boolean | undefined;
+        priorityHint?: number | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    schemaVersion: 1;
+    items: {
+        name: string;
+        mode: "active" | "audit";
+        type: "mutation" | "validation";
+        config: Record<string, unknown>;
+        enabled: boolean;
+        timeoutMs: number;
+        phase: "request" | "response";
+        failOpen: boolean;
+        priorityHint: number;
+        model?: {
+            provider: string;
+            instruction: string;
+            model?: string | undefined;
+        } | undefined;
+        command?: string[] | undefined;
+    }[];
+}, {
+    schemaVersion: 1;
+    items: {
+        name: string;
+        type: "mutation" | "validation";
+        phase: "request" | "response";
+        mode?: "active" | "audit" | undefined;
+        model?: {
+            provider: string;
+            instruction: string;
+            model?: string | undefined;
+        } | undefined;
+        command?: string[] | undefined;
+        config?: Record<string, unknown> | undefined;
+        enabled?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        failOpen?: boolean | undefined;
+        priorityHint?: number | undefined;
+    }[];
+}>, {
+    schemaVersion: 1;
+    items: {
+        name: string;
+        mode: "active" | "audit";
+        type: "mutation" | "validation";
+        config: Record<string, unknown>;
+        enabled: boolean;
+        timeoutMs: number;
+        phase: "request" | "response";
+        failOpen: boolean;
+        priorityHint: number;
+        model?: {
+            provider: string;
+            instruction: string;
+            model?: string | undefined;
+        } | undefined;
+        command?: string[] | undefined;
+    }[];
+}, {
+    schemaVersion: 1;
+    items: {
+        name: string;
+        type: "mutation" | "validation";
+        phase: "request" | "response";
+        mode?: "active" | "audit" | undefined;
+        model?: {
+            provider: string;
+            instruction: string;
+            model?: string | undefined;
+        } | undefined;
+        command?: string[] | undefined;
+        config?: Record<string, unknown> | undefined;
+        enabled?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        failOpen?: boolean | undefined;
+        priorityHint?: number | undefined;
+    }[];
+}>;
+export declare class AgentInterceptorConfigError extends Error {
+    readonly code = "INTERCEPTOR_CONFIG_INVALID";
+    constructor(agentId: string, message: string);
+}
+export declare function parseAgentInterceptorItems(agentId: string, raw: unknown): AgentInterceptorItem[] | undefined;

package/dist/agent-interceptor/types.d.ts

@@ -0,0 +1,88 @@
+export type InterceptorPhase = 'request' | 'response';
+export type InterceptorType = 'mutation' | 'validation';
+export type InterceptorMode = 'active' | 'audit';
+export type InterceptorSeverity = 'error' | 'warn' | 'info';
+export type InterceptorOutcome = 'applied' | 'unchanged' | 'blocked' | 'audit' | 'bypassed' | 'failed';
+export declare const INTERCEPTOR_CONFIG_INVALID = "INTERCEPTOR_CONFIG_INVALID";
+export declare const INTERCEPTOR_BLOCKED = "INTERCEPTOR_BLOCKED";
+export declare const INTERCEPTOR_STOPPED = "INTERCEPTOR_STOPPED";
+export declare const INTERCEPTOR_FAILED = "INTERCEPTOR_FAILED";
+export interface AgentInterceptorItem {
+    name: string;
+    type: InterceptorType;
+    phase: InterceptorPhase;
+    mode: InterceptorMode;
+    failOpen: boolean;
+    priorityHint: number;
+    timeoutMs: number;
+    enabled: boolean;
+    config: Record<string, unknown>;
+    command?: string[];
+    model?: {
+        provider: string;
+        model?: string;
+        instruction: string;
+    };
+}
+export interface InterceptorMessage {
+    role: string;
+    content: string;
+}
+export interface InterceptorVerdict {
+    valid: boolean;
+    severity?: InterceptorSeverity;
+    messages: Array<{
+        message: string;
+    }>;
+}
+export interface InterceptorError {
+    code: number | string;
+    message: string;
+}
+export interface InterceptorUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    costUsd: number;
+}
+export interface InterceptorStepLog {
+    name: string;
+    type: InterceptorType;
+    phase: InterceptorPhase;
+    mode: InterceptorMode;
+    outcome: InterceptorOutcome;
+    failOpen: boolean;
+    durationMs: number;
+    error?: InterceptorError;
+    before: string;
+    after?: string;
+    verdict?: InterceptorVerdict;
+    usage?: InterceptorUsage;
+    stderr?: string;
+}
+export type InterceptorInvocation = {
+    ok: true;
+    result: unknown;
+    durationMs: number;
+    usage?: InterceptorUsage;
+    stderr?: string;
+} | {
+    ok: false;
+    code: number | string;
+    message: string;
+    durationMs: number;
+    usage?: InterceptorUsage;
+    stderr?: string;
+};
+export interface InterceptorLaneRun {
+    phase: InterceptorPhase;
+    status: 'passed' | 'blocked' | 'stopped';
+    text: string;
+    changed: boolean;
+    steps: InterceptorStepLog[];
+    blocked?: {
+        step: string;
+        code: typeof INTERCEPTOR_BLOCKED;
+        message: string;
+    };
+}

package/dist/app/app.d.ts

@@ -1,4 +1,5 @@
 import type { UiContentMediaType } from './content-media-types.js';
+import type { AppScheduleDirective, AppScheduleSnapshot, ToolScheduleDeclaration } from './schedule-contract.js';
 export type JsonObject = Record<string, unknown>;
 export type JsonSchema = Readonly<{
     type: 'object';
@@ -66,11 +67,12 @@ export interface ToolOptions {
         allow: readonly string[];
     }>;
     readonly content?: ToolContentDeclaration;
+    readonly schedule?: ToolScheduleDeclaration;
 }
 export interface AppContext {
     readonly instanceId: string;
     readonly threadId: string | null;
-    readonly actor: 'user' | 'agent';
+    readonly actor: 'user' | 'agent' | 'schedule';
     readonly requestId: string;
     readonly nowMs: number;
 }
@@ -78,6 +80,7 @@ export interface AppRuntimeOptions<State extends JsonObject = JsonObject> {
     readonly state?: State;
     readonly workspaceRoot: string;
     readonly context?: AppContext;
+    readonly schedule?: AppScheduleSnapshot;
 }
 export type AppFailureOutcome = 'failed' | 'rejected';
 export interface AppErrorMapping {
@@ -111,8 +114,13 @@ export declare class CrewXApp<State extends JsonObject = JsonObject> {
     private answerBody;
     private answerRange;
     private readonly callContext;
+    private readonly callSchedule;
+    private scheduleDirective;
     readonly workspaceRoot: string;
     constructor(options?: AppRuntimeOptions<State>);
+    get schedule(): AppScheduleSnapshot | undefined;
+    requestSchedule(enabled: boolean): void;
+    get didRequestSchedule(): AppScheduleDirective | undefined;
     get context(): AppContext;
     get state(): DeepReadonly<State>;
     get didSetState(): boolean;
@@ -142,6 +150,7 @@ export type CrewXAppConstructor = (new (options: AppRuntimeOptions) => CrewXApp)
 type DecoratedMethod<This, Input extends object, Result extends ToolResult> = (this: This, input: Input, content: ToolContent) => Result;
 export declare function Tool(options: ToolOptions): <This, Input extends object, Result extends ToolResult>(_method: DecoratedMethod<This, Input, Result>, context: ClassMethodDecoratorContext<This, DecoratedMethod<This, Input, Result>>) => void;
 export declare function getToolDeclarations(appClass: CrewXAppConstructor): ToolDeclaration[];
+export declare function declaresSchedule(appClass: CrewXAppConstructor): boolean;
 export declare function generateToolDeclarations(appClass: CrewXAppConstructor): JsonObject[];
 export declare function generateManifest(appClass: CrewXAppConstructor, backendCommand: readonly string[]): JsonObject;
 export declare function isPlainRecord(value: unknown): value is JsonObject;

package/dist/app/index.d.ts

@@ -1,6 +1,8 @@
 export { AppError, CrewXApp, Tool, generateManifest, generateToolDeclarations, getToolDeclarations, } from './app.js';
 export type { AppContext, AppDefinition, AppErrorContext, AppErrorMapping, AppErrorOptions, AppFailureOutcome, AppRuntimeOptions, ContentRange, ContentRangeRequest, CrewXAppConstructor, DeepReadonly, JsonObject, JsonSchema, ToolContent, ToolContentDeclaration, ToolContentInput, ToolContentOutput, ToolDeclaration, ToolOptions, ToolResult, } from './app.js';
 export { readAppContext } from './context.js';
+export { APP_SCHEDULE_ACTOR_KIND, APP_SCHEDULE_INERT_COMMAND, APP_SCHEDULE_INSTANCE_PREFIX, APP_SCHEDULE_INTERVALS_MINUTES, APP_SCHEDULE_MAX_PER_APP, APP_SCHEDULE_PERIODIC_REASONS, APP_SCHEDULE_TIMEOUT_MS, SCHEDULE_TRIGGERS, isAppSchedulePeriodicReason, isAppScheduleCode, isAppScheduleIntervalMinutes, isAppScheduleTimeoutMs, } from './schedule-contract.js';
+export type { AppScheduleDirective, AppScheduleIntervalMinutes, AppSchedulePeriodic, AppSchedulePeriodicReason, AppScheduleRunVerdict, AppScheduleSnapshot, AppScheduleStatus, ScheduleTrigger, ToolScheduleDeclaration, } from './schedule-contract.js';
 export { APP_TOOLS_FILE, APP_TOOLS_SCHEMA_VERSION, APP_TOOL_ENTRY } from './tool-mode.js';
 export { SKILL_BACKEND_ENV_NAMES, isSkillBackendEnv } from './backend-env.js';
 export type { SkillBackendEnvName } from './backend-env.js';