@rynx-ai/workspace 0.1.9

package/dist/agent-execution.d.ts

@@ -0,0 +1,290 @@
+import type { WorkspaceAgentRuntimeId } from "./agent-options.js";
+import type { WorkspaceAgentPlacement, WorkspaceAgentSkillRevisionRef } from "./types.js";
+export declare const WORKSPACE_AGENT_EXECUTION_SPEC_VERSION: 1;
+export declare const WORKSPACE_AGENT_ENVIRONMENT_SPEC_VERSION: 1;
+/**
+ * Version 1 always creates one independent persistent Workdir. Repository and
+ * Artifact inputs intentionally remain an empty, versioned extension point.
+ */
+export interface WorkspaceAgentRunEnvironmentSpecV1 {
+    schemaVersion: typeof WORKSPACE_AGENT_ENVIRONMENT_SPEC_VERSION;
+    workdir: {
+        sources: [];
+    };
+}
+export type WorkspaceAgentRunStatus = "queued" | "running" | "cancelling" | "idle" | "failed" | "blocked" | "abandoned" | "cancelled";
+export type WorkspaceAgentTurnStatus = "queued" | "offered" | "assigned" | "preparing" | "running" | "cancelling" | "completed" | "failed" | "execution_unknown" | "cancelled";
+export type WorkspaceAgentTurnWaitReason = "fixed_device_offline" | "fixed_device_busy" | "fixed_device_incompatible" | "waiting_device" | "no_compatible_device" | "waiting_capacity";
+export type WorkspaceAgentAttemptStatus = "assigned" | "preparing" | "running" | "cancelling" | "completed" | "failed" | "execution_unknown" | "cancelled";
+/** Product surface that owns and presents this Agent Session. */
+export type WorkspaceAgentRunOrigin = {
+    type: "agent_test";
+};
+/** AgentRun.id is the only product-facing Session ID. */
+export interface WorkspaceAgentRun {
+    id: string;
+    workspaceId: string;
+    agentId: string;
+    agentRevisionId: string;
+    origin: WorkspaceAgentRunOrigin;
+    /** `idle` means the Session has no active Turn and may accept a follow-up.
+     * The latest Turn retains its own independent completed/failed outcome. */
+    status: WorkspaceAgentRunStatus;
+    pinnedDeviceId?: string;
+    activeTurnId?: string;
+    environment: WorkspaceAgentRunEnvironmentSpecV1;
+    createdByOpenId?: string;
+    createdByName?: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Time the latest active Turn or terminal Session transition settled. */
+    settledAt?: string;
+}
+export interface WorkspaceAgentRunTurn {
+    id: string;
+    workspaceId: string;
+    runId: string;
+    sequence: number;
+    kind: "initial" | "follow_up";
+    message: string;
+    status: WorkspaceAgentTurnStatus;
+    waitReason?: WorkspaceAgentTurnWaitReason;
+    /** Durable automatic-retry gate. The scheduler must not offer before it. */
+    retryNotBefore?: string;
+    currentAttemptId?: string;
+    createdByOpenId?: string;
+    createdByName?: string;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    /** Durable execution output projected from this Turn's terminal event. */
+    result?: WorkspaceAgentTurnResult;
+}
+export interface WorkspaceAgentTurnResult {
+    finalResponse?: string;
+    artifactKeys?: string[];
+}
+export interface WorkspaceAgentRunAttempt {
+    id: string;
+    workspaceId: string;
+    runId: string;
+    turnId: string;
+    attemptNumber: number;
+    deviceId: string;
+    status: WorkspaceAgentAttemptStatus;
+    errorCode?: string;
+    errorMessage?: string;
+    createdAt: string;
+    updatedAt: string;
+    startedAt?: string;
+    completedAt?: string;
+}
+export interface WorkspaceAgentRunCancellation {
+    requestId: string;
+    workspaceId: string;
+    runId: string;
+    reason: string;
+    outcome: "pending" | "applied" | "too_late" | "unknown";
+    createdAt: string;
+    resolvedAt?: string;
+}
+export type WorkspaceAgentInteractionStatus = "pending" | "resolving" | "resolved" | "cancelled" | "expired";
+export interface WorkspaceAgentInteractionOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+export type WorkspaceAgentInteractionField = {
+    id: string;
+    type: "text";
+    label: string;
+    description?: string;
+    required?: boolean;
+    secret?: boolean;
+    multiline?: boolean;
+    placeholder?: string;
+} | {
+    id: string;
+    type: "select";
+    label: string;
+    description?: string;
+    required?: boolean;
+    multiple?: boolean;
+    allowOther?: boolean;
+    options: WorkspaceAgentInteractionOption[];
+};
+export interface WorkspaceAgentInteractionAction {
+    id: string;
+    label: string;
+    description?: string;
+    style?: "primary" | "secondary" | "danger";
+    requiresAnswers: boolean;
+}
+/** Product-safe projection of a provider-neutral Session interaction. */
+export interface WorkspaceAgentInteractionRequest {
+    interactionId: string;
+    kind: "question" | "permission" | "form";
+    title: string;
+    description?: string;
+    fields: WorkspaceAgentInteractionField[];
+    actions: WorkspaceAgentInteractionAction[];
+    context?: {
+        summary?: string;
+        toolName?: string;
+        command?: string;
+        cwd?: string;
+        diff?: string;
+    };
+    createdAt: string;
+}
+export type WorkspaceAgentInteractionAnswer = string | string[];
+/** Answers are command-only input. Durable public projections expose actionId only. */
+export interface WorkspaceAgentInteractionResolution {
+    actionId: string;
+    answers?: Record<string, WorkspaceAgentInteractionAnswer>;
+}
+export interface WorkspaceAgentInteraction {
+    id: string;
+    workspaceId: string;
+    runId: string;
+    turnId: string;
+    attemptId: string;
+    status: WorkspaceAgentInteractionStatus;
+    request: WorkspaceAgentInteractionRequest;
+    resolvedActionId?: string;
+    resolvedByOpenId?: string;
+    resolvedByName?: string;
+    resolutionError?: string;
+    createdAt: string;
+    updatedAt: string;
+    resolvedAt?: string;
+}
+export interface WorkspaceResolveAgentInteractionInput {
+    workspaceId: string;
+    runId: string;
+    interactionId: string;
+    requestId: string;
+    resolution: WorkspaceAgentInteractionResolution;
+    resolvedBy?: {
+        openId: string;
+        name?: string;
+        email?: string;
+    };
+}
+export type WorkspaceResolveAgentInteractionResult = {
+    status: "created" | "replayed";
+    interaction: WorkspaceAgentInteraction;
+    deviceId: string;
+} | {
+    status: "not_found";
+} | {
+    status: "conflict" | "invalid";
+    error: string;
+};
+export interface WorkspaceAgentRunEvent {
+    id: string;
+    workspaceId: string;
+    runId: string;
+    sequence: number;
+    turnId?: string;
+    attemptId?: string;
+    attemptSequence?: number;
+    type: string;
+    data: Record<string, unknown>;
+    occurredAt: string;
+}
+export interface WorkspaceAgentRunTurnPage {
+    turns: WorkspaceAgentRunTurn[];
+    attempts: WorkspaceAgentRunAttempt[];
+    interactions: WorkspaceAgentInteraction[];
+    turnPage: {
+        hasMore: boolean;
+        /** Exclusive Turn sequence cursor for the next older page. */
+        nextBeforeSequence?: number;
+    };
+}
+export interface WorkspaceAgentRunDetail extends WorkspaceAgentRun, WorkspaceAgentRunTurnPage {
+    cancellations: WorkspaceAgentRunCancellation[];
+    /** Durable SSE cursor captured with this detail snapshot. */
+    latestEventSequence: number;
+}
+export interface WorkspaceCreateAgentRunInput {
+    workspaceId: string;
+    agentId: string;
+    origin: WorkspaceAgentRunOrigin;
+    /** Initial Session binding. Automatic placement is pinned after assignment. */
+    placement: WorkspaceAgentPlacement;
+    requestId: string;
+    message: string;
+    createdBy?: {
+        openId: string;
+        name?: string;
+        email?: string;
+    };
+}
+export type WorkspaceCreateAgentRunResult = {
+    status: "created" | "replayed";
+    run: WorkspaceAgentRunDetail;
+} | {
+    status: "not_found";
+} | {
+    status: "invalid";
+    error: string;
+};
+export interface WorkspaceAppendAgentRunTurnInput {
+    workspaceId: string;
+    runId: string;
+    requestId: string;
+    message: string;
+    createdBy?: {
+        openId: string;
+        name?: string;
+        email?: string;
+    };
+}
+export type WorkspaceAppendAgentRunTurnResult = {
+    status: "created" | "replayed";
+    run: WorkspaceAgentRunDetail;
+} | {
+    status: "not_found";
+} | {
+    status: "conflict" | "invalid";
+    error: string;
+};
+/** Explicit operator recovery for an Attempt whose execution outcome cannot
+ * be proven. Abandoning never rolls back filesystem or external effects. */
+export interface WorkspaceResolveBlockedAgentRunInput {
+    workspaceId: string;
+    runId: string;
+    requestId: string;
+    action: "abandon";
+}
+export type WorkspaceResolveBlockedAgentRunResult = {
+    status: "abandoned" | "replayed";
+    run: WorkspaceAgentRunDetail;
+} | {
+    status: "not_found";
+} | {
+    status: "conflict" | "invalid";
+    error: string;
+};
+/** Immutable payload sent only after a Daemon accepts an Offer. */
+export interface WorkspaceAgentExecutionSpecV1 {
+    schemaVersion: typeof WORKSPACE_AGENT_EXECUTION_SPEC_VERSION;
+    runId: string;
+    turnId: string;
+    attemptId: string;
+    agentRevisionId: string;
+    agent: {
+        name: string;
+        description?: string;
+        instructions: string;
+        runtime: WorkspaceAgentRuntimeId;
+        model: string;
+        reasoningEffort?: string;
+        skills: WorkspaceAgentSkillRevisionRef[];
+    };
+    environment: WorkspaceAgentRunEnvironmentSpecV1;
+    message: string;
+}
+export declare function emptyWorkspaceAgentRunEnvironment(): WorkspaceAgentRunEnvironmentSpecV1;

package/dist/agent-execution.js

@@ -0,0 +1,8 @@
+export const WORKSPACE_AGENT_EXECUTION_SPEC_VERSION = 1;
+export const WORKSPACE_AGENT_ENVIRONMENT_SPEC_VERSION = 1;
+export function emptyWorkspaceAgentRunEnvironment() {
+    return {
+        schemaVersion: WORKSPACE_AGENT_ENVIRONMENT_SPEC_VERSION,
+        workdir: { sources: [] },
+    };
+}

package/dist/agent-options.d.ts

@@ -0,0 +1,26 @@
+import type { WorkspaceAgentModelOption, WorkspaceAgentReasoningOption } from "./types.js";
+export type WorkspaceAgentRuntimeId = "codex" | "traex" | "claude";
+export declare const WORKSPACE_AGENT_RUNTIME_IDS: readonly WorkspaceAgentRuntimeId[];
+export interface WorkspaceAgentRuntimeProfile {
+    id: WorkspaceAgentRuntimeId;
+    displayName: string;
+    defaultBinary: string;
+}
+export declare const WORKSPACE_AGENT_RUNTIME_PROFILES: Record<WorkspaceAgentRuntimeId, WorkspaceAgentRuntimeProfile>;
+export interface WorkspaceAgentModelEnv {
+    CODEX_MODEL?: string;
+    TRAEX_MODEL?: string;
+    TRAECLI_MODEL?: string;
+    CLAUDE_MODEL?: string;
+}
+export declare function isWorkspaceAgentRuntimeId(value: unknown): value is WorkspaceAgentRuntimeId;
+export declare function getWorkspaceAgentRuntimeProfile(id: WorkspaceAgentRuntimeId): WorkspaceAgentRuntimeProfile;
+export declare function workspaceAgentModelOptions(runtime: string, env?: WorkspaceAgentModelEnv): WorkspaceAgentModelOption[];
+export declare function workspaceReasoningLabel(value: string): string;
+export declare function workspaceAgentReasoningOptions(runtime: string, model: string): WorkspaceAgentReasoningOption[];
+export interface WorkspaceAgentRuntimeCandidate {
+    runtime: string;
+    models?: WorkspaceAgentModelOption[];
+}
+/** Hard compatibility predicate used before a device receives a targeted Offer. */
+export declare function workspaceRuntimeSupportsAgent(candidate: WorkspaceAgentRuntimeCandidate, runtime: WorkspaceAgentRuntimeId, model: string, reasoningEffort?: string): boolean;

package/dist/agent-options.js

@@ -0,0 +1,106 @@
+export const WORKSPACE_AGENT_RUNTIME_IDS = ["codex", "traex", "claude"];
+export const WORKSPACE_AGENT_RUNTIME_PROFILES = {
+    codex: {
+        id: "codex",
+        displayName: "Codex",
+        defaultBinary: "codex",
+    },
+    traex: {
+        id: "traex",
+        displayName: "Traex",
+        defaultBinary: "traex",
+    },
+    claude: {
+        id: "claude",
+        displayName: "Claude Code",
+        defaultBinary: "claude",
+    },
+};
+export function isWorkspaceAgentRuntimeId(value) {
+    return value === "codex" || value === "traex" || value === "claude";
+}
+export function getWorkspaceAgentRuntimeProfile(id) {
+    return WORKSPACE_AGENT_RUNTIME_PROFILES[id];
+}
+export function workspaceAgentModelOptions(runtime, env = {}) {
+    if (!isWorkspaceAgentRuntimeId(runtime))
+        return [];
+    if (runtime === "claude")
+        return claudeModelOptions(env.CLAUDE_MODEL);
+    const model = runtime === "traex"
+        ? env.TRAEX_MODEL?.trim() || env.TRAECLI_MODEL?.trim()
+        : env.CODEX_MODEL?.trim() || "gpt-5.5";
+    return model
+        ? [
+            {
+                id: model,
+                label: model,
+                isDefault: true,
+            },
+        ]
+        : [];
+}
+const CLAUDE_DEFAULT_MODEL = "claude-sonnet-4-6";
+const CLAUDE_MODEL_IDS = [
+    { id: "claude-opus-4-8", label: "Claude Opus 4.8" },
+    { id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6" },
+    { id: "claude-haiku-4-5", label: "Claude Haiku 4.5" },
+    { id: "claude-opus-4-7", label: "Claude Opus 4.7" },
+    { id: "claude-opus-4-6", label: "Claude Opus 4.6" },
+    { id: "claude-fable-5", label: "Claude Fable 5" },
+];
+function claudeModelOptions(configuredModel) {
+    const defaultModel = configuredModel?.trim() || CLAUDE_DEFAULT_MODEL;
+    const known = new Set(CLAUDE_MODEL_IDS.map((model) => model.id));
+    const models = known.has(defaultModel)
+        ? CLAUDE_MODEL_IDS
+        : [{ id: defaultModel, label: defaultModel }, ...CLAUDE_MODEL_IDS];
+    return models.map((model) => ({
+        id: model.id,
+        label: model.label,
+        isDefault: model.id === defaultModel,
+    }));
+}
+const REASONING_LABELS = {
+    none: "None",
+    minimal: "Minimal",
+    low: "Low",
+    medium: "Medium",
+    high: "High",
+    xhigh: "Extra high",
+    max: "Max",
+    ultra: "Ultra",
+};
+export function workspaceReasoningLabel(value) {
+    return REASONING_LABELS[value] ?? value;
+}
+export function workspaceAgentReasoningOptions(runtime, model) {
+    const values = runtime === "claude"
+        ? model.toLowerCase().includes("opus")
+            ? ["low", "medium", "high", "xhigh"]
+            : ["low", "medium", "high"]
+        : runtime === "codex" || runtime === "traex"
+            ? ["none", "minimal", "low", "medium", "high", "xhigh"]
+            : [];
+    return values.map((value) => ({
+        value,
+        label: workspaceReasoningLabel(value),
+    }));
+}
+/** Hard compatibility predicate used before a device receives a targeted Offer. */
+export function workspaceRuntimeSupportsAgent(candidate, runtime, model, reasoningEffort) {
+    if (candidate.runtime !== runtime)
+        return false;
+    const models = candidate.models?.length
+        ? candidate.models
+        : workspaceAgentModelOptions(runtime);
+    const selected = models.find((option) => option.id === model);
+    if (!selected)
+        return false;
+    if (!reasoningEffort)
+        return true;
+    const efforts = selected.supportedReasoningEfforts?.length
+        ? selected.supportedReasoningEfforts
+        : workspaceAgentReasoningOptions(runtime, model);
+    return efforts.some((option) => option.value === reasoningEffort);
+}

package/dist/agent-scheduler.d.ts

@@ -0,0 +1,149 @@
+import type { WorkspaceAgentAttemptEventMessage, WorkspaceAgentInteractionResolveAckMessage, WorkspaceAgentInteractionResolveMessage, WorkspaceAgentTurnAssignAckMessage, WorkspaceAgentTurnAssignMessage, WorkspaceAgentTurnCancelAckMessage, WorkspaceAgentTurnCancelMessage, WorkspaceAgentTurnOfferBusyReason, WorkspaceAgentTurnOfferMessage } from "./device-protocol.js";
+import type { WorkspaceAgentTurnWaitReason } from "./agent-execution.js";
+export interface WorkspaceAgentSchedulableTurn {
+    workspaceId: string;
+    runId: string;
+    turnId: string;
+    agentId: string;
+    agentRevisionId: string;
+    pinnedDeviceId?: string;
+}
+export interface WorkspaceAgentOutboxCommand {
+    id: string;
+    workspaceId: string;
+    deviceId: string;
+    attemptId?: string;
+    kind: "turn.assign" | "turn.cancel" | "interaction.resolve";
+    payload: WorkspaceAgentTurnAssignMessage | WorkspaceAgentTurnCancelMessage | WorkspaceAgentInteractionResolveMessage;
+    state: "pending" | "sent" | "acked" | "cancelled";
+    availableAt: string;
+    sendAttempts: number;
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+    sentAt?: string;
+    ackedAt?: string;
+}
+/** Durable operations required by the Server scheduler. Live socket presence
+ * and candidate ranking deliberately remain outside this interface. */
+export interface WorkspaceAgentSchedulerPlane {
+    listAgentSchedulableTurns(input?: {
+        workspaceId?: string;
+        limit?: number;
+        now?: string;
+    }): WorkspaceAgentSchedulableTurn[];
+    markAgentTurnWaiting(input: {
+        workspaceId: string;
+        runId: string;
+        turnId: string;
+        reason: WorkspaceAgentTurnWaitReason;
+    }): "committed" | "duplicate" | "stale";
+    createAgentTurnOffer(input: {
+        id?: string;
+        workspaceId: string;
+        runId: string;
+        turnId: string;
+        deviceId: string;
+        expiresAt: string;
+    }): {
+        status: "created" | "replayed";
+        message: WorkspaceAgentTurnOfferMessage;
+    } | {
+        status: "not_found" | "conflict" | "invalid";
+        error: string;
+    };
+    acceptAgentTurnOffer(input: {
+        workspaceId: string;
+        deviceId: string;
+        offerId: string;
+        daemonInstanceId: string;
+        permitId: string;
+        leaseMs: number;
+    }): {
+        status: "assigned" | "replayed";
+        command: WorkspaceAgentTurnAssignMessage;
+    } | {
+        status: "expired" | "stale" | "conflict";
+        error: string;
+    };
+    markAgentTurnOfferBusy(input: {
+        workspaceId: string;
+        deviceId: string;
+        offerId: string;
+        daemonInstanceId: string;
+        reason: WorkspaceAgentTurnOfferBusyReason;
+    }): "committed" | "duplicate" | "expired" | "stale";
+    expireAgentTurnOffers(input?: {
+        workspaceId?: string;
+        now?: string;
+    }): number;
+    listAgentOutboxCommands(input: {
+        workspaceId: string;
+        deviceId: string;
+        daemonInstanceId: string;
+        /** Recovery-only: include acknowledged Assignments that still belong to
+         * the current leased Attempt for this exact daemon process instance. */
+        includeAcknowledgedAssignments?: boolean;
+        limit?: number;
+        now?: string;
+    }): WorkspaceAgentOutboxCommand[];
+    markAgentOutboxCommandSent(input: {
+        workspaceId: string;
+        deviceId: string;
+        commandId: string;
+        error?: string;
+    }): "sent" | "stale";
+    acknowledgeAgentTurnAssignment(input: {
+        workspaceId: string;
+        deviceId: string;
+        ack: WorkspaceAgentTurnAssignAckMessage;
+    }): "committed" | "duplicate" | "stale";
+    requestAgentTurnCancellation(input: {
+        workspaceId: string;
+        runId: string;
+        requestId: string;
+        reason: string;
+    }): {
+        status: "created" | "replayed";
+        command: WorkspaceAgentTurnCancelMessage;
+    } | {
+        status: "cancelled";
+    } | {
+        status: "not_found" | "not_active" | "stale" | "conflict";
+        error: string;
+    };
+    acknowledgeAgentTurnCancellation(input: {
+        workspaceId: string;
+        deviceId: string;
+        ack: WorkspaceAgentTurnCancelAckMessage;
+    }): "committed" | "duplicate" | "stale";
+    acknowledgeAgentInteractionResolution(input: {
+        workspaceId: string;
+        deviceId: string;
+        ack: WorkspaceAgentInteractionResolveAckMessage;
+    }): "committed" | "duplicate" | "stale";
+    renewAgentAttemptLease(input: {
+        workspaceId: string;
+        deviceId: string;
+        attemptId: string;
+        assignmentEpoch: number;
+        leaseToken: string;
+        daemonInstanceId: string;
+        leaseMs: number;
+    }): {
+        disposition: "renewed" | "stale";
+        leaseExpiresAt?: string;
+    };
+    commitAgentAttemptEvent(input: {
+        workspaceId: string;
+        deviceId: string;
+        event: WorkspaceAgentAttemptEventMessage;
+    }): {
+        disposition: "committed" | "duplicate" | "stale" | "rejected";
+        runSequence?: number;
+    };
+    expireAgentAttemptLeases(input?: {
+        workspaceId?: string;
+        now?: string;
+    }): number;
+}

package/dist/agent-scheduler.js

@@ -0,0 +1 @@
+export {};