@crewx/sdk 0.9.0-rc.164 → 0.9.0-rc.165

package/dist/mcp-app/app-job-bridge.d.ts

@@ -0,0 +1,30 @@
+import { type AppJobChannel, type AppJobView, type AppJobWireHandle } from '../app/job-wire.js';
+import type { AppJobOperation, AppJobStopReason, AppJobTrigger } from '../app/job-contract.js';
+import { AppJobCoordinator, type AppJobHandle, type AppJobLaunchRequest, type AppJobOwner, type AppJobSnapshot, type ResolvedAppJob } from './app-job.js';
+export interface AppJobControlSession {
+    readonly coordinator: AppJobCoordinator;
+    readonly owner: AppJobOwner;
+    readonly definitionHash: string;
+    readonly job: ResolvedAppJob | undefined;
+    readonly actionId: string;
+    readonly operations: readonly AppJobOperation[];
+    readonly trigger: AppJobTrigger;
+}
+export type AppJobControlAnswer = {
+    readonly kind: 'reply';
+    readonly line: string;
+} | {
+    readonly kind: 'close';
+    readonly code: 'APP_JOB_BRIDGE_INVALID';
+};
+export declare function answerAppJobControlLine(session: AppJobControlSession, line: string): AppJobControlAnswer;
+export interface AppJobRunBinding {
+    readonly coordinator: AppJobCoordinator;
+    readonly handle: AppJobHandle;
+}
+export type AppJobRunAnswer = 'accepted' | 'ignored' | 'invalid';
+export declare function answerAppJobRunLine(binding: AppJobRunBinding, line: string): AppJobRunAnswer;
+export declare function encodeAppJobStopPush(handle: AppJobWireHandle, reason: AppJobStopReason): string;
+export declare function toAppJobView(snapshot: AppJobSnapshot): AppJobView;
+export declare function buildAppJobRunChannel(request: Pick<AppJobLaunchRequest, 'handle'>, fd: number): AppJobChannel;
+export declare function buildAppJobControlChannel(operations: readonly AppJobOperation[], fd: number): AppJobChannel;

package/dist/mcp-app/app-job-bridge.example.d.ts

@@ -0,0 +1,36 @@
+import type { UiDefinitionInput } from '../ui-instance/types.js';
+import { type AppJobControlSession } from './app-job-bridge.js';
+import { AppJobCoordinator, type AppJobOwner } from './app-job.js';
+export declare const CODE_MAP_HOST_FD = 3;
+export interface HostPipeEnd {
+    write(line: string): void;
+    onData(listener: (chunk: string) => void): void;
+    onEnd(listener: () => void): void;
+    close(): void;
+}
+export interface HostChild {
+    readonly pipe: HostPipeEnd;
+    kill(): Promise<void>;
+}
+export type HostSpawn = (options: {
+    readonly env: Readonly<Record<string, string>>;
+    readonly fd: number;
+}) => HostChild;
+export interface CodeMapHostOptions {
+    readonly owner: AppJobOwner;
+    readonly definitionHash: string;
+    readonly definition: UiDefinitionInput;
+    readonly spawnRun: HostSpawn;
+    readonly now: () => number;
+    readonly stopGraceMs?: number;
+    readonly newRunId?: () => string;
+}
+export interface CodeMapHost {
+    readonly coordinator: AppJobCoordinator;
+    sessionFor(call: {
+        readonly actionId: string;
+        readonly actorKind: 'user' | 'agent' | 'schedule';
+    }): AppJobControlSession;
+    serveControlChild(session: AppJobControlSession, pipe: HostPipeEnd): void;
+}
+export declare function createCodeMapHost(options: CodeMapHostOptions): CodeMapHost;

package/dist/mcp-app/app-job.d.ts

@@ -0,0 +1,168 @@
+import { type AppJobOutcome, type AppJobRefusalCode, type AppJobState, type AppJobStopReason, type AppJobTrigger } from '../app/job-contract.js';
+export type { AppJobRefusalCode, AppJobStopReason } from '../app/job-contract.js';
+import type { UiDefinitionInput } from '../ui-instance/types.js';
+import type { AppScheduleOwnerSource } from './app-schedule.js';
+export interface AppJobOwner {
+    readonly workspaceId: string;
+    readonly appId: string;
+    readonly source: AppScheduleOwnerSource;
+}
+export interface ResolvedAppJob {
+    readonly actionId: string;
+    readonly deadlineMs: number;
+}
+export declare function resolveDeclaredJob(definition: Pick<UiDefinitionInput, 'actions'>): ResolvedAppJob | undefined;
+export declare function appJobOwnerKey(owner: AppJobOwner): string;
+export interface AppJobError {
+    readonly code: string;
+    readonly recoverable: boolean;
+}
+export interface AppJobHandle {
+    readonly runId: string;
+    readonly generation: number;
+    readonly ownerKey: string;
+}
+export interface AppJobLaunchRequest {
+    readonly handle: AppJobHandle;
+    readonly owner: AppJobOwner;
+    readonly actionId: string;
+    readonly definitionHash: string;
+    readonly deadlineMs: number;
+    readonly trigger: AppJobTrigger;
+    readonly resumeFromRunId: string | null;
+}
+export interface AppJobExecutionPort {
+    launch(request: AppJobLaunchRequest): Promise<string>;
+    requestStop(ref: string): Promise<void>;
+    terminate(ref: string): Promise<void>;
+}
+export type AppJobReport = {
+    readonly kind: 'heartbeat';
+} | {
+    readonly kind: 'progress';
+    readonly phase: string;
+    readonly completed?: number;
+    readonly total?: number;
+    readonly resumable?: boolean;
+} | {
+    readonly kind: 'completed';
+} | {
+    readonly kind: 'failed';
+    readonly code: string;
+    readonly recoverable: boolean;
+} | {
+    readonly kind: 'exited';
+};
+export type AppJobReportResult = 'accepted' | 'ignored' | 'invalid';
+export interface AppJobStartRequest {
+    readonly owner: AppJobOwner;
+    readonly definitionHash: string;
+    readonly job: ResolvedAppJob | undefined;
+    readonly trigger: AppJobTrigger;
+    readonly authorizedActionId: string;
+}
+export type AppJobStartRefusalCode = Extract<AppJobRefusalCode, ('APP_JOB_NOT_DECLARED' | 'APP_JOB_NOT_AUTHORIZED' | 'APP_JOB_SELF_START' | 'APP_JOB_OWNER_INVALID' | 'APP_JOB_DEFINITION_INVALID' | 'APP_JOB_DEFINITION_CHANGED' | 'APP_JOB_DEADLINE_INVALID' | 'APP_JOB_SHUTTING_DOWN')>;
+export type AppJobStartResult = {
+    readonly kind: 'started';
+    readonly snapshot: AppJobSnapshot;
+} | {
+    readonly kind: 'attached';
+    readonly snapshot: AppJobSnapshot;
+} | {
+    readonly kind: 'refused';
+    readonly code: AppJobStartRefusalCode;
+};
+export type AppJobCancelRefusalCode = 'APP_JOB_OWNER_MISMATCH' | 'APP_JOB_STALE_HANDLE' | 'APP_JOB_NOT_ACTIVE';
+export type AppJobCancelResult = {
+    readonly kind: 'stopping';
+    readonly snapshot: AppJobSnapshot;
+} | {
+    readonly kind: 'refused';
+    readonly code: AppJobCancelRefusalCode;
+};
+export interface AppJobSnapshot {
+    readonly handle: AppJobHandle;
+    readonly state: AppJobState;
+    readonly stopReason: AppJobStopReason | null;
+    readonly trigger: AppJobTrigger;
+    readonly definitionHash: string;
+    readonly resumedFromRunId: string | null;
+    readonly outcome: AppJobOutcome | null;
+    readonly phase: string | null;
+    readonly completed: number | null;
+    readonly total: number | null;
+    readonly resumable: boolean;
+    readonly lastHeartbeatAt: string | null;
+    readonly startedAt: string;
+    readonly finishedAt: string | null;
+    readonly error: AppJobError | null;
+}
+export interface AppJobRecord {
+    readonly runId: string;
+    readonly owner: AppJobOwner;
+    readonly generation: number;
+    readonly actionId: string;
+    readonly definitionHash: string;
+    readonly deadlineMs: number;
+    readonly trigger: AppJobTrigger;
+    readonly resumedFromRunId: string | null;
+    readonly state: AppJobState;
+    readonly outcome: AppJobOutcome | null;
+    readonly phase: string | null;
+    readonly completed: number | null;
+    readonly total: number | null;
+    readonly resumable: boolean;
+    readonly startedAt: number;
+    readonly lastHeartbeatAt: number | null;
+    readonly finishedAt: number | null;
+    readonly error: AppJobError | null;
+}
+export interface AppJobEvent {
+    readonly kind: 'started' | 'attached' | 'stop_requested' | 'finished';
+    readonly runId: string;
+    readonly generation: number;
+    readonly owner: AppJobOwner;
+    readonly trigger: AppJobTrigger;
+    readonly stopReason: AppJobStopReason | null;
+    readonly outcome: AppJobOutcome | null;
+    readonly errorCode: string | null;
+    readonly at: string;
+}
+export interface AppJobCoordinatorOptions {
+    readonly port: AppJobExecutionPort;
+    readonly now: () => number;
+    readonly records?: readonly AppJobRecord[];
+    readonly onEvent?: (event: AppJobEvent) => void;
+    readonly newRunId?: () => string;
+    readonly stopGraceMs?: number;
+}
+export declare class AppJobCoordinator {
+    private readonly port;
+    private readonly now;
+    private readonly newRunId;
+    private readonly onEvent;
+    private readonly stopGraceMs;
+    private readonly runs;
+    private readonly latestByOwner;
+    private readonly drainWaiters;
+    private shuttingDown;
+    constructor(options: AppJobCoordinatorOptions);
+    start(request: AppJobStartRequest): AppJobStartResult;
+    cancel(handle: AppJobHandle): AppJobCancelResult;
+    report(handle: AppJobHandle, report: AppJobReport): AppJobReportResult;
+    status(owner: AppJobOwner): AppJobSnapshot | null;
+    tick(): void;
+    shutdown(): Promise<void>;
+    records(): readonly AppJobRecord[];
+    private launch;
+    private beginStop;
+    private requestStop;
+    private terminate;
+    private finish;
+    private restore;
+    private settle;
+    private emit;
+    private unfinishedCount;
+    private drain;
+    private snapshot;
+}

package/dist/mcp-app/index.d.ts

@@ -39,3 +39,7 @@ export { buildWorkspaceAppSnapshot, discoverWorkspaceAppSnapshot, reconfirmWorks
 export type { WorkspaceAppSnapshot, WorkspaceAppSnapshotBuildOptions, WorkspaceAppSnapshotOptions, WorkspaceAppSnapshotReconfirmResult, WorkspaceAppSnapshotResource, WorkspaceAppSnapshotInitialState, WorkspaceAppInitialState, } from './workspace-snapshot.js';
 export { appScheduleCommandLabel, cronExpressionForInterval, decideScheduleDirective, planScheduledFire, resolveDeclaredSchedule, scheduleTemplateFor, toScheduledRunVerdict, toScheduleSnapshot, } from './app-schedule.js';
 export type { AppScheduleActorKind, AppScheduleAvailability, AppScheduleBinding, AppScheduleOwner, AppScheduleOwnerSource, AppScheduleRowView, AppScheduleTemplate, AppScheduledRunPayload, AppScheduledRunPlan, ResolvedAppSchedule, ScheduleDirectiveDecision, ScheduleLifecycleEntry, ScheduleLifecyclePlan, ScheduledAppLaunchRequest, } from './app-schedule.js';
+export { AppJobCoordinator, appJobOwnerKey, resolveDeclaredJob, } from './app-job.js';
+export type { AppJobCancelRefusalCode, AppJobCancelResult, AppJobCoordinatorOptions, AppJobError, AppJobEvent, AppJobExecutionPort, AppJobHandle, AppJobLaunchRequest, AppJobOwner, AppJobRecord, AppJobRefusalCode, AppJobReport, AppJobReportResult, AppJobSnapshot, AppJobStartRefusalCode, AppJobStartRequest, AppJobStartResult, AppJobStopReason, ResolvedAppJob, } from './app-job.js';
+export { answerAppJobControlLine, answerAppJobRunLine, buildAppJobControlChannel, buildAppJobRunChannel, encodeAppJobStopPush, toAppJobView, } from './app-job-bridge.js';
+export type { AppJobControlAnswer, AppJobControlSession, AppJobRunAnswer, AppJobRunBinding, } from './app-job-bridge.js';

package/dist/mcp-app/skill-backend.d.ts

@@ -1,5 +1,7 @@
 import { SKILL_BACKEND_CONTENT_SCHEMA_VERSION, SKILL_BACKEND_MAX_INPUT_BYTES, SKILL_BACKEND_MAX_OUTPUT_BYTES } from '../app/protocol.js';
 import { type AppScheduleDirective, type AppScheduleSnapshot } from '../app/schedule-contract.js';
+import type { AppJobOperation } from '../app/job-contract.js';
+import { type AppJobChannel } from '../app/job-wire.js';
 import type { ContentFrame, UiContentMediaType, UiContentRangeRequest } from './content-channel.js';
 import type { JsonObject, UiExternalActionHandlerRegistration, UiSkillBackendEnvironmentKey } from '../ui-instance/types.js';
 import type { UiPluginNormalizedManifestV2 } from '../ui-plugin/types.js';
@@ -71,6 +73,7 @@ interface SkillBackendExecutionRequestBase {
         };
     };
     readonly environment?: Readonly<Partial<Record<UiSkillBackendEnvironmentKey, string>>>;
+    readonly jobAccess?: readonly AppJobOperation[];
 }
 export type SkillBackendExecutionRequest = SkillBackendExecutionRequestBase & ({
     readonly source: 'bundled';
@@ -86,8 +89,11 @@ export interface SkillBackendChildEnvironment {
     readonly CREWX_APP_REQUEST_ID: string;
     readonly CREWX_APP_NOW_MS: string;
     readonly CREWX_APP_ACTOR_KIND: 'user' | 'agent' | 'schedule';
+    readonly CREWX_APP_JOB_CHANNEL?: string;
 }
-export declare function buildSkillBackendChildEnvironment(request: Pick<SkillBackendExecutionRequest, 'requestId' | 'reservationNowMs' | 'actorKind'>): SkillBackendChildEnvironment;
+export declare function buildSkillBackendChildEnvironment(request: Pick<SkillBackendExecutionRequest, 'requestId' | 'reservationNowMs' | 'actorKind'>, options?: {
+    readonly jobChannel?: AppJobChannel;
+}): SkillBackendChildEnvironment;
 export interface VerifiedBundleSkillSpawnRequest {
     readonly appId: string;
     readonly packageDir: string;