@crowdedkingdoms/crowdyjs 11.1.0 → 12.0.0

package/dist/crowdy-agent/controller.d.ts

@@ -0,0 +1,144 @@
+import { type AgentErrorV1 } from './errors.js';
+import type { CrowdyAgentBrowserToolDispatcher } from './browser-dispatcher.js';
+import type { CrowdyAgentApprovalV1, CrowdyAgentBudgetV1, CrowdyAgentCheckpointV1, CrowdyAgentEventV1, CrowdyAgentLeaseV1, CrowdyAgentMessageV1, CrowdyAgentMode, CrowdyAgentPreemptionReason, CrowdyAgentRegisteredToolV1, CrowdyAgentSessionV1, CrowdyAgentToolTimelineItemV1 } from './types.js';
+import type { CrowdyAgentCreateSessionInputV1, CrowdyStudioAgentTransportV1 } from './transport.js';
+export type CrowdyStudioAgentConnectionState = 'DISCONNECTED' | 'ATTACHING' | 'REPLAYING' | 'CONNECTED' | 'RECONNECTING' | 'ERROR';
+export interface CrowdyStudioAgentStateV1 {
+    readonly connection: CrowdyStudioAgentConnectionState;
+    readonly session: CrowdyAgentSessionV1 | null;
+    readonly clientEpoch: string | null;
+    readonly lastContiguousSeq: string;
+    readonly lastAcknowledgedSeq: string;
+    readonly events: readonly CrowdyAgentEventV1[];
+    readonly messages: readonly CrowdyAgentMessageV1[];
+    readonly streamingText: string;
+    readonly tools: readonly CrowdyAgentToolTimelineItemV1[];
+    readonly approvals: readonly CrowdyAgentApprovalV1[];
+    readonly leases: readonly CrowdyAgentLeaseV1[];
+    readonly checkpoints: readonly CrowdyAgentCheckpointV1[];
+    readonly budget: CrowdyAgentBudgetV1 | null;
+    readonly toolDescriptors: readonly CrowdyAgentRegisteredToolV1[];
+    readonly lastHeartbeatAt: string | null;
+    readonly playLeaseFreshUntil: string | null;
+    readonly lastError: AgentErrorV1 | null;
+    readonly reconnectRequired: boolean;
+}
+export interface CrowdyStudioAgentControllerOptionsV1 {
+    readonly transport: CrowdyStudioAgentTransportV1;
+    readonly sessionId?: string;
+    readonly createSession?: CrowdyAgentCreateSessionInputV1 | (() => CrowdyAgentCreateSessionInputV1 | Promise<CrowdyAgentCreateSessionInputV1>);
+    /** Resolve the currently selected, fully saved Studio project at attach time. */
+    readonly resolveProjectBinding?: () => {
+        readonly projectId?: string;
+        readonly gridId?: string;
+    } | Promise<{
+        readonly projectId?: string;
+        readonly gridId?: string;
+    }>;
+    readonly browserDispatcher?: CrowdyAgentBrowserToolDispatcher;
+    /** Stable browser UUID reused across fresh attach epochs. */
+    readonly clientInstanceId?: string;
+    /** Flush autosave and validate conflicts before accepting a human turn. */
+    readonly beforeAgentWork?: (mode: CrowdyAgentMode) => void | Promise<void>;
+    /** Called synchronously for local preemption before transport cleanup. */
+    readonly onPreempt?: (reason: CrowdyAgentPreemptionReason) => void;
+    readonly onEpochAttached?: (clientEpoch: string) => void;
+    readonly onLeaseChanged?: (lease: CrowdyAgentLeaseV1) => void;
+    readonly createIdempotencyKey?: (operation: string) => string;
+    readonly historyPageSize?: number;
+    readonly maxRetainedEvents?: number;
+    readonly autoReconnect?: boolean;
+    readonly reconnectDelayMs?: number;
+    readonly maxReconnectAttempts?: number;
+    readonly heartbeatIntervalMs?: number;
+    readonly heartbeatStaleMs?: number;
+    readonly workspaceRenewIntervalMs?: number;
+    readonly onStateChange?: (state: CrowdyStudioAgentStateV1) => void;
+}
+/**
+ * Durable session client for the `crowdy.studio-agent/1` protocol. The
+ * transport is injectable and contains no generated GraphQL dependency.
+ */
+export declare class CrowdyStudioAgentController {
+    private readonly options;
+    private state;
+    private readonly listeners;
+    private readonly buffered;
+    private readonly appliedEventIds;
+    private subscription;
+    private generation;
+    private drainPromise;
+    private acknowledgePromise;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private workspaceRenewTimer;
+    private reconnectAttempts;
+    private keySequence;
+    private readonly clientInstanceId;
+    private pageVisible;
+    private destroyed;
+    constructor(options: CrowdyStudioAgentControllerOptionsV1);
+    getState(): CrowdyStudioAgentStateV1;
+    subscribe(listener: (state: CrowdyStudioAgentStateV1) => void): () => void;
+    setPageVisible(visible: boolean): void;
+    initialize(): Promise<void>;
+    /**
+     * Fail closed when the human selects another project. The v1 Game API has no
+     * set-project mutation, so callers must create/remount a session for it.
+     */
+    projectSelectionChanged(projectId: string | undefined): void;
+    reconnect(): Promise<void>;
+    sendMessage(content: string): Promise<{
+        runId: string;
+    }>;
+    setMode(mode: CrowdyAgentMode): Promise<void>;
+    approveTool(toolCallId: string, expectedArgumentHash?: string): Promise<void>;
+    rejectTool(toolCallId: string, reason?: string): Promise<void>;
+    grantPlayLease(input: {
+        readonly scopes: readonly string[];
+        readonly durationSeconds: number;
+        readonly controlledEntityId: string;
+        readonly hostCapabilityRevision: string;
+    }): Promise<CrowdyAgentLeaseV1>;
+    revokeLease(leaseId: string, reason?: CrowdyAgentPreemptionReason): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    cancelRun(runId?: string | undefined): Promise<void>;
+    /** Immediate human Stop: local preemption happens before transport calls. */
+    stop(): Promise<void>;
+    /** Editor changes synchronously preempt Build before best-effort cleanup. */
+    preemptForHumanEdit(): void;
+    restoreCheckpoint(checkpointId: string): Promise<void>;
+    close(): Promise<void>;
+    destroy(): void;
+    private attach;
+    private replayHistory;
+    private enqueueEvent;
+    private startDrain;
+    private bufferEvent;
+    private drainBuffered;
+    private applyEvent;
+    private dispatchBrowserTool;
+    private scheduleAcknowledge;
+    private handleDisconnect;
+    private refreshHeartbeat;
+    private sendHeartbeat;
+    private stopHeartbeat;
+    private refreshWorkspaceRenewal;
+    private renewWorkspaceLease;
+    private stopWorkspaceRenewal;
+    private scheduleReconnect;
+    private loadRemoteContext;
+    private assertProjectBinding;
+    private mutationContext;
+    private nextKey;
+    private patchSession;
+    private upsertLease;
+    private disconnectSubscription;
+    private requireSession;
+    private preemptLocal;
+    private update;
+    private fail;
+    private ensureAlive;
+}
+//# sourceMappingURL=controller.d.ts.map

package/dist/crowdy-agent/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/crowdy-agent/controller.ts"],"names":[],"mappings":"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"}