@actana/sdk 0.2.2

package/dist/core-client.d.ts

@@ -0,0 +1,616 @@
+import { type CoreLinkErrorCode, type CoreLinkEvent, type CoreLinkHarnessAvailabilityMap, type CoreLinkLaunchProcessKillResult, type CoreLinkMultiConnectionCapability, type CoreLinkProjectMutation, type CoreLinkProjectSnapshot, type CoreLinkPtyReplay, type CoreLinkPtySpawnOptions, type CoreLinkRequestFrame, type CoreLinkResponseFrame, type CoreLinkSessionSnapshot, type CoreLinkSessionTakenFrom, type CoreLinkTaskMutation, type CoreLinkTaskSnapshot } from "./core-link-frames.ts";
+import { CoreLinkTransport, type CoreLinkAuthErrorReason, type CoreLinkDataFrame, type CoreLinkExitFrame, type CoreLinkHeartbeatOptions } from "./core-link-transport.ts";
+import { type CoreLinkSocketFactory, type CoreLinkTlsMaterial } from "./core-link-socket.ts";
+import { type CoreRegistrationBlob } from "./core-registration-blob.ts";
+/**
+ * Request frames that only mean anything against a Core announcing
+ * `multiConnection` on `ready` (ADR 0024 D11) — the one list
+ * {@link CoreClient.canSendMultiConnectionFrames} guards.
+ *
+ * `ptySubscribe` / `ptyUnsubscribe` (ADR 0024 D2) are the first entries: a Core
+ * that fans a PTY out per subscription is exactly a multi-connection Core, and
+ * one that never announced the capability has no subscription list to put a PTY
+ * on. The Session lock's `claim` / `release` / `forceTakeover` (D3–D7) joined
+ * them for the same reason in its own key: a single-connection Core has no lock
+ * table to address, because it evicts every client but one and therefore has
+ * nothing for a lock to arbitrate between. `reclaim` (D9) is the sharpest of the
+ * three: a single-connection Core evicts its predecessor on connect *already*,
+ * so the frame asks for what that Core has just done, out of a lock table it
+ * does not have.
+ *
+ * Being in this set is not the whole story for a frame whose caller has
+ * something better to do than fail. A caller that can degrade consults
+ * {@link CoreClient.canSendMultiConnectionFrames} and takes the
+ * single-connection route itself — see {@link CoreClient.ptySubscribe} and
+ * {@link CoreClient.claim}, which both do exactly that. The rejection in
+ * {@link CoreClient.request} is the backstop for callers that ask without
+ * checking, not the designed path for the frames listed here.
+ */
+export declare const MULTI_CONNECTION_ONLY_FRAME_TYPES: ReadonlySet<CoreLinkRequestFrame["type"]>;
+/**
+ * The rejection a caller gets when the Core answers a request with an `error`
+ * frame — carrying that frame's machine-readable {@link CoreLinkErrorCode}
+ * alongside its prose (issue 144).
+ *
+ * `code` exists precisely so a caller does not have to match on `message`, and a
+ * client that threw a bare `Error` would put the parsing back that the field was
+ * added to remove. It is optional on the wire and optional here: absent on every
+ * error that shipped before the field, so a reader takes the code when it is
+ * there and falls back to the message when it is not — never the reverse.
+ *
+ * `session-locked` is its first value and the reason this class exists: a
+ * mutation refused because another Core client holds that Session throws,
+ * whereas a mutation aimed at a Session this Core no longer has resolves
+ * (`ok: false` / `task: null`). One of the two is worth retrying after a claim
+ * and the other never is, and telling them apart is the caller's whole job.
+ */
+export declare class CoreLinkRequestError extends Error {
+    /** The `code` off the `error` frame, when it carried one. */
+    readonly code?: CoreLinkErrorCode;
+    constructor(message: string, code?: CoreLinkErrorCode);
+}
+/** Thrown when a bearer is refused: `expired`, `bad-signature`, `malformed`. */
+export declare class CoreLinkAuthError extends Error {
+    readonly reason: CoreLinkAuthErrorReason;
+    constructor(reason: CoreLinkAuthErrorReason);
+}
+/** What a connected Core told this client about itself, on `ready` and `authOk`. */
+export type CoreConnectionInfo = {
+    /** The protocol version off `ready`, or null when the frame carried none. */
+    protocolVersion: string | null;
+    /** Does this build speak that version? See `coreLinkProtocolCompatible`. */
+    compatible: boolean;
+    /** The `multiConnection` capability, or null on a single-connection Core. */
+    multiConnection: CoreLinkMultiConnectionCapability | null;
+    /** The `coreId` off `authOk`; null when no bearer was configured. */
+    coreId: string | null;
+    /** The bearer's expiry off `authOk`; null when no bearer was configured. */
+    bearerExpiresAt: number | null;
+};
+export type CoreClientOptions = {
+    /** The core-link URL to dial. Ignored when {@link CoreClientOptions.blob} is set. */
+    url?: string;
+    /** PEM material for the mTLS handshake (ADR 0002). Ignored when `blob` is set. */
+    tls?: CoreLinkTlsMaterial | null;
+    /**
+     * The signed bearer presented in the `auth` frame (ADR 0002). Required by
+     * every real Core; omitted only by a loopback rig or a test.
+     */
+    bearer?: string | null;
+    /**
+     * A registration blob — endpoint, PEM material and bearer in one object, which
+     * is how a Core client is actually configured (#129 D1/D9). Set this and the
+     * three fields above are read off it.
+     */
+    blob?: CoreRegistrationBlob;
+    /**
+     * How to open the socket. Defaults to the Node `ws` dial with the `tls`
+     * material — the only transport that can present a client certificate.
+     * Injectable for tests and for a runtime with its own WebSocket.
+     */
+    createSocket?: CoreLinkSocketFactory;
+    /** Deadline for {@link CoreClient.connect}. Default 30s. */
+    connectTimeoutMs?: number;
+    /** Default deadline for one request. Default 30s. */
+    requestTimeoutMs?: number;
+    /**
+     * Arm the connection heartbeat. Off by default here and on in
+     * {@link DurableCoreClient} — see {@link CoreLinkTransport}.
+     */
+    heartbeat?: CoreLinkHeartbeatOptions | false;
+    /**
+     * This client's stable Core client id, presented on every connection so a Core
+     * reaps the socket this one replaces (ADR 0024 D9).
+     *
+     * Default: a fresh id per instance. That is honest rather than a shortcut —
+     * the id's job is to span a *reconnect*, and only a client that reconnects has
+     * one to span. Pass one explicitly to make it outlive the process, and keep it
+     * per Core client: it must never be anything off the registration blob, which
+     * is machine-scoped, or the Panel, the CLI and every automation on that
+     * machine become one client, each reconnect reaping the others.
+     */
+    clientId?: string;
+    /**
+     * Overrides {@link MULTI_CONNECTION_ONLY_FRAME_TYPES}. Exists only so a test
+     * can drive the rejection in {@link CoreClient.request} with a stand-in frame
+     * type: the real entries all degrade at their call sites rather than reach
+     * that backstop. Production never passes it.
+     */
+    multiConnectionOnlyFrameTypes?: ReadonlySet<string>;
+};
+/** Default deadline for a dial: `ready` plus, with a bearer, `authOk`. */
+export declare const DEFAULT_CONNECT_TIMEOUT_MS = 30000;
+/** Default deadline for one request/response round trip. */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+type Unsubscribe = () => void;
+/**
+ * A Core client over one core link.
+ *
+ * Lifecycle: construct, `await connect()`, ask, `close()`. Construction opens
+ * nothing — a client you have not connected has sent no bytes, which is what
+ * makes `connect()`'s rejection the one place a dial failure is reported.
+ */
+export declare class CoreClient {
+    /** The URL this client dials. Public because a log line without it is a riddle. */
+    readonly url: string;
+    /**
+     * This client's Core client id — the same string on every connection it opens,
+     * which is the whole of what makes a reconnect reclaimable (ADR 0024 D9).
+     *
+     * Readonly: an id that moved between connections would reclaim nothing and
+     * leave the predecessor holding its Sessions for the full heartbeat timeout,
+     * which is the exact failure the frame exists to remove.
+     */
+    readonly clientId: string;
+    protected readonly createSocket: CoreLinkSocketFactory;
+    protected readonly bearer: string | null;
+    protected readonly heartbeat: CoreLinkHeartbeatOptions | false;
+    private readonly connectTimeoutMs;
+    private readonly requestTimeoutMs;
+    private readonly multiConnectionOnlyFrameTypes;
+    protected transport: CoreLinkTransport | null;
+    protected closed: boolean;
+    /**
+     * True once a `subscribe` has gone out for this client — see
+     * {@link subscribeEvents}. Per client rather than per connection: it records
+     * that this client *wants* the event stream, which is what a reconnecting
+     * subclass re-asks for, and what stops a second caller asking twice.
+     */
+    private eventsSubscribed;
+    /** True once this connection has been established — reset per connection. */
+    private established;
+    /** Requests written to no socket yet. They survive a reconnect; a timeout is what ends them. */
+    private readonly queue;
+    /** Requests on the wire right now, so a dying socket can fail them at once. */
+    private readonly inFlight;
+    private connectPromise;
+    private connectSettle;
+    /** This connection's `ready` frame; null before it lands and after a drop. */
+    private ready;
+    /**
+     * This Core's `multiConnection` capability as announced on the *current*
+     * connection; null when absent and before `ready` lands.
+     *
+     * Re-read on every `ready` rather than remembered across connections: a Core
+     * can be downgraded, and a stale `true` here would send frames the Core no
+     * longer understands. Null until the frame arrives, so the gate is closed
+     * during the window where the answer is genuinely unknown.
+     */
+    private multiConnection;
+    private authOkFrame;
+    private readonly readyListeners;
+    private readonly dataListeners;
+    private readonly exitListeners;
+    private readonly eventListeners;
+    private readonly eventsReplayedListeners;
+    private readonly authOkListeners;
+    private readonly authErrorListeners;
+    private readonly disconnectedListeners;
+    private readonly reclaimedListeners;
+    constructor(opts: CoreClientOptions);
+    /** Build a client straight off a registration blob (#129 D1). */
+    static fromRegistrationBlob(blob: CoreRegistrationBlob, opts?: Omit<CoreClientOptions, "blob" | "url" | "tls" | "bearer">): CoreClient;
+    /**
+     * Open the link and settle when the Core has said who it is: resolves after
+     * `ready` and, when a bearer is configured, after `authOk`.
+     *
+     * Idempotent **while it is in flight** — a second call returns the first
+     * call's promise, so two callers racing to connect share one socket rather
+     * than opening two. Once it settles the memo is dropped, and what a later
+     * call gets is the state of the link *now*: the current connection's info if
+     * one is up, and a fresh attempt if none is.
+     *
+     * That distinction is the whole point. A memo kept past its rejection is a
+     * client that reports itself permanently unconnectable — a durable client
+     * whose connect deadline expired once would hand every later caller that same
+     * rejection long after its supervisor had reconnected, because nothing here
+     * ever cleared it (issue 153 review, note 3; #156 builds on this).
+     *
+     * Rejects on a refused bearer, on a socket that closed before it was
+     * established, and on the connect deadline. A {@link DurableCoreClient} keeps
+     * retrying underneath regardless; what rejects there is this promise, not the
+     * client.
+     */
+    connect(): Promise<CoreConnectionInfo>;
+    /**
+     * Is a reconnect already pending, so `connect()` must not dial itself? Never
+     * for a one-shot client, which has no supervisor; {@link DurableCoreClient}
+     * overrides it with its backoff timer.
+     */
+    protected reconnectScheduled(): boolean;
+    /**
+     * Open one connection and wire it to this client. The transport is per socket;
+     * every listener above is per client, which is what lets a durable subclass
+     * replace the former without anything above noticing.
+     */
+    protected openTransport(): void;
+    /**
+     * The connection is up, authenticated if it had to be, and the capability off
+     * `ready` is known. What a fresh connection owes the Core goes here.
+     *
+     * `reclaim` is the whole of it for a one-shot client, and it is fire-and-forget
+     * by design (ADR 0024 D9): nothing waits on the answer, because the locks have
+     * already moved by the time it is written, and a reclaim that never lands costs
+     * the 45-second heartbeat timeout it was shortening — a slower path to the same
+     * state, never a wrong one.
+     *
+     * Overridden by {@link DurableCoreClient}, which owes the Core rather more.
+     */
+    protected onConnectionEstablished(): void;
+    /**
+     * Establish the connection once both halves of "established" are true: the
+     * Core has said who it is (`ready`), and the link can be written to (open, and
+     * authenticated when a bearer was configured).
+     *
+     * **Whichever lands last is what triggers it**, and that is not a fixed order.
+     * With a bearer it is `authOk`, well after `ready`. Without one, writability
+     * rides the socket opening and `ready` normally follows — but a Core that got
+     * its frame in first would otherwise have the connection's opening frames sent
+     * against a socket that is not writable yet, and a `subscribe` dropped there is
+     * a client that never receives an event again. Waiting for both removes the
+     * ordering assumption instead of relying on it.
+     */
+    private maybeEstablish;
+    /** The socket is gone. A one-shot client is done; a durable one reconnects. */
+    protected onConnectionClosed(reason?: string): void;
+    private settleConnect;
+    private failConnect;
+    /** What the current connection said about itself. */
+    connectionInfo(): CoreConnectionInfo;
+    /** True once the Core has accepted this connection's bearer. */
+    isAuthenticated(): boolean;
+    /** True while a link is up and able to carry a frame. */
+    isConnected(): boolean;
+    /**
+     * May this Core be sent frames only a multi-connection Core understands — the
+     * Session lock's `claim`, the per-connection PTY subscription, and whatever
+     * else lands under ADR 0024?
+     *
+     * **The one predicate to consult before sending any such frame.** False means
+     * do not send it: not send-and-handle-the-error, not send-and-hope. The Core on
+     * the other end is a single-connection build that would answer an unknown frame
+     * with an error frame at best, and the caller is expected to have a
+     * single-connection path already — that path is what shipped before this
+     * capability existed.
+     *
+     * False before `ready` lands and after a drop, for as long as the answer is
+     * unknown. A caller that needs the capability at startup awaits
+     * {@link connect}, whose answer carries it, rather than reading this on the
+     * first tick.
+     */
+    canSendMultiConnectionFrames(): boolean;
+    /**
+     * This connection's `multiConnection` capability, or null. For callers that
+     * need the version rather than the yes/no — the gate is
+     * {@link canSendMultiConnectionFrames}.
+     */
+    multiConnectionCapability(): CoreLinkMultiConnectionCapability | null;
+    /** Hang up. Rejects every outstanding request; fires no `onDisconnected`. */
+    close(): void;
+    /**
+     * Send any core-link request frame and resolve with the Core's raw response
+     * frame — errors included, as frames rather than rejections.
+     *
+     * This is the seam a router forwards through. A router that had to go through
+     * the typed methods below would unwrap each response only to re-wrap it, and
+     * would have to invent a shape for the failures those methods turn into
+     * rejections. Handing it the frame keeps it a router rather than a translator.
+     *
+     * The `reqId` on the frame passed in is ignored — the transport owns
+     * correlation on its own socket, and the returned frame carries the id it
+     * assigned. A caller matching answers to its own callers (the Panel does,
+     * across many browsers) keys on its own id and rewrites it on the way back.
+     *
+     * A frame issued while no link is up is **queued, not refused**: it goes out
+     * when one comes up, or its deadline ends it. That is what makes a call made
+     * during a reconnect work rather than needing every call site to retry.
+     */
+    request(frame: CoreLinkRequestFrame, timeoutMs?: number): Promise<CoreLinkResponseFrame>;
+    /**
+     * Send now if there is an established link, otherwise hold it for the next
+     * one.
+     *
+     * **Established, not merely writable.** On the no-bearer path writability
+     * rides the socket opening and can land before `ready`, so a request *issued*
+     * in that window would go out ahead of the `reclaim` and `subscribe` this
+     * connection owes the Core — the ordering `onConnectionEstablished` documents
+     * as load-bearing, and the same property `onWritable`'s guard keeps for a
+     * request that was already queued. Both doors, one rule: nothing reaches the
+     * wire before the connection has been established (issue 153 review, #156).
+     */
+    private dispatch;
+    /** Drain what was waiting for a link, in the order it was asked for. */
+    private flushQueue;
+    /**
+     * Fail every request that was on the wire when the socket died. Their replies
+     * can never arrive, so leaving them pending only makes a caller wait out its
+     * whole deadline before it can retry on the next connection.
+     */
+    private failInFlight;
+    private forget;
+    private settle;
+    /** Send a request and unwrap the Core's answer into the value it carries. */
+    protected rpc(frame: CoreLinkRequestFrame, timeoutMs?: number): Promise<unknown>;
+    /**
+     * Send a fire-and-forget frame on the current connection. False when there is
+     * no writable connection to put it on — for the frames whose answer is a
+     * stream and whose retry is the next connection re-sending them anyway.
+     */
+    protected sendNow(frame: CoreLinkRequestFrame, reqIdPrefix?: string): boolean;
+    /**
+     * Present this client's Core client id, so the Core closes the socket this
+     * connection replaces and moves its Session locks here (ADR 0024 D9).
+     *
+     * The answer is not discarded, though (issue 147). `taskIds` names the Sessions
+     * whose locks came across, and that is a fact no layer above can derive: this
+     * connection did not claim them, the Core logged no event for the transfer —
+     * the locks moved in place, which is exactly the atomicity D9 needs — so until
+     * something asks for a fresh snapshot nothing else on the link says this client
+     * is holding them again. Hence {@link onReclaimed}.
+     *
+     * **Against a Core that does not announce `multiConnection`, this sends
+     * nothing** — the same consult-the-gate-and-degrade shape
+     * {@link ptySubscribe} and {@link claim} take, and here the degraded behaviour
+     * is not merely acceptable but identical: such a Core evicts the previous
+     * connection when this one opens, which is precisely what the frame asks for.
+     */
+    protected sendReclaim(): void;
+    /**
+     * One PTY's bytes, as the transport parsed them. Nothing above re-parses a raw
+     * message: this is the frame, typed against the SDK's own schema.
+     *
+     * A Core sends a PTY's `data` only to the connections that asked for it, so
+     * {@link ptySubscribe} is what makes this fire at all against a
+     * multi-connection Core.
+     */
+    onData(cb: (frame: CoreLinkDataFrame) => void): Unsubscribe;
+    /** One PTY's exit, on the same terms as {@link onData}. */
+    onExit(cb: (frame: CoreLinkExitFrame) => void): Unsubscribe;
+    /**
+     * Notified on every connection's `ready` frame with what the Core says about
+     * itself — the protocol version, whether this build speaks it, and the
+     * `multiConnection` capability. Fires on every (re)connect, so a Core that
+     * comes back after an update reports itself compatible with no extra plumbing.
+     */
+    onReady(cb: (info: CoreConnectionInfo) => void): Unsubscribe;
+    /**
+     * Domain events off the Core's monotonic log — task status, hooks, session
+     * finish, PTY lifecycle. A one-shot client receives only what arrives while it
+     * is connected; the cursor, the replay and the dedupe that make a *gap*
+     * recoverable are {@link DurableCoreClient}'s.
+     */
+    onEvent(cb: (msg: {
+        event: CoreLinkEvent;
+    }) => void): Unsubscribe;
+    /**
+     * Ask this Core for its event log: the tail past `lastEventId`, then live
+     * push for as long as this connection lasts.
+     *
+     * Fire-and-forget, because the answer is a *stream* — the replay tail as
+     * `event` frames and the {@link onEventsReplayed} marker behind them — rather
+     * than a reqId-correlated response. Returns false when there was no writable
+     * connection to put the frame on.
+     *
+     * A one-shot client sends this only if it is asked to. That is the difference
+     * between the two entry points here: {@link DurableCoreClient} owes the Core a
+     * subscribe on every connection and sends one through this method, whereas a
+     * program that connects to ask one question wants no event stream at all.
+     * What made it public is the session layer (issue 155): a script that starts a
+     * Session and waits for the harness to finish is reading the Core's own
+     * report of that, and the report is an event.
+     *
+     * `lastEventId` defaults to 0, which asks for the whole tail the Core will
+     * serve. That is the honest default for a caller with no cursor — the
+     * alternative is inventing a high-water mark, and a cursor that runs ahead of
+     * the log stops live push entirely. A caller that keeps a cursor passes it.
+     */
+    subscribeEvents(lastEventId?: number): boolean;
+    /**
+     * Has a `subscribe` gone out on this client's behalf?
+     *
+     * For a caller that needs the event stream but does not know whether the
+     * client it was handed is already receiving one — a durable client subscribes
+     * itself, a one-shot client does not, and a second subscribe would replay the
+     * tail a second time.
+     */
+    isSubscribedToEvents(): boolean;
+    /** Notified when a `subscribe` replay tail has been fully streamed. */
+    onEventsReplayed(cb: (msg: {
+        lastEventId: number;
+    }) => void): Unsubscribe;
+    /**
+     * Notified once per connection when the Core accepts the bearer. `exp` is the
+     * session expiry — a caller can hint "session expires at".
+     */
+    onAuthOk(cb: (msg: {
+        coreId: string;
+        exp: number;
+    }) => void): Unsubscribe;
+    /**
+     * Notified when the Core refuses the bearer. The Core closes the socket right
+     * after; an expired bearer keeps failing until a reissued blob is pasted (ADR
+     * 0003).
+     */
+    onAuthError(cb: (msg: {
+        reason: CoreLinkAuthErrorReason;
+    }) => void): Unsubscribe;
+    /**
+     * Notified whenever the socket goes down — a dropped connection, a Core
+     * restart, a dial that never completed. `close()` does not fire it: that is
+     * this client hanging up, not the Core going away.
+     */
+    onDisconnected(cb: (msg: {
+        error?: string;
+    }) => void): Unsubscribe;
+    /**
+     * What this client's `reclaim` reaped, once per connection that sent one (ADR
+     * 0024 D9, issue 147 is its consumer).
+     *
+     * Fires only on a Core that announces `multiConnection`, because only such a
+     * Core is sent the frame at all. `taskIds` is often empty and an empty list
+     * never means the id was unknown — it means this client held nothing when its
+     * previous socket went quiet, which is the ordinary case.
+     */
+    onReclaimed(cb: (msg: {
+        replaced: boolean;
+        taskIds: string[];
+    }) => void): Unsubscribe;
+    /** Hand one event to the listeners. Overridden where a cursor is kept. */
+    protected deliverEvent(event: CoreLinkEvent): void;
+    /** Hand the end-of-replay marker on. Overridden where a cursor is kept. */
+    protected deliverEventsReplayed(lastEventId: number): void;
+    spawn(opts: CoreLinkPtySpawnOptions): Promise<{
+        ptyId: string;
+    }>;
+    write(ptyId: string, data: string): Promise<boolean>;
+    resize(ptyId: string, cols: number, rows: number): Promise<boolean>;
+    kill(ptyId: string): Promise<boolean>;
+    killLaunchProcesses(opts: {
+        cwd: string;
+        commands: string[];
+        ports?: number[];
+    }): Promise<CoreLinkLaunchProcessKillResult>;
+    findByTask(taskId: string): Promise<{
+        ptyId: string | null;
+    }>;
+    /**
+     * See {@link CoreLinkRequestFrame} `replay` — `sinceSeq` asks for the tail past
+     * a cursor (a reattach); omitting it asks for the whole scrollback.
+     */
+    replay(ptyId: string, sinceSeq?: number): Promise<CoreLinkPtyReplay>;
+    /**
+     * Ask this Core for one PTY's byte stream (ADR 0024 D2). Until a client
+     * subscribes, {@link onData}/{@link onExit} never fire for that `ptyId` — a
+     * Core fans output out to the connections that asked and to no others.
+     *
+     * `catchUp` says a `replay` for this PTY follows and the Core must hold the
+     * live stream until it has been served, so the caller never paints live bytes
+     * in front of its own scrollback. A caller that sets it owes that replay;
+     * nothing else releases the hold.
+     *
+     * **Against a Core that does not announce `multiConnection`, this sends nothing
+     * and resolves** (ADR 0024 D11). That is the deliberate single-connection
+     * fallback, not a swallowed failure: such a Core fans every PTY out to every
+     * connection, so the caller is already receiving the bytes it just asked for,
+     * and the subscription it would send is a frame that Core has no vocabulary
+     * for. Resolving says what is true — this client renders that PTY — which is
+     * the only thing the caller acts on.
+     */
+    ptySubscribe(ptyId: string, opts?: {
+        catchUp?: boolean;
+    }): Promise<void>;
+    /**
+     * Stop receiving one PTY's stream. Same fallback as {@link ptySubscribe}, for
+     * the same reason: against a capability-less Core there is no subscription to
+     * drop, because its fan-out is unconditional and cannot be narrowed by a frame
+     * it does not know.
+     */
+    ptyUnsubscribe(ptyId: string): Promise<void>;
+    /**
+     * Take this Session's write lock (ADR 0024 D6).
+     *
+     * `granted: false` means another Core client holds it — an answer, not a
+     * failure, and the only way past it is {@link forceTakeover}. Idempotent for a
+     * client that already holds the Session.
+     *
+     * **Against a Core that does not announce `multiConnection`, this sends nothing
+     * and answers `{ supported: false, granted: false }`.** Such a Core evicts
+     * every client but one, so there is nothing for a lock to arbitrate between and
+     * no table to put a claim in.
+     *
+     * `supported: false` must never be rendered as read-only. It says this Core has
+     * no Session lock at all, so every mutation this client makes will be served —
+     * the opposite of what `granted: false` says. A caller that treats the two the
+     * same makes a single-connection Core look permanently locked to an operator
+     * who is in fact its only client.
+     */
+    claim(taskId: string): Promise<{
+        supported: boolean;
+        granted: boolean;
+    }>;
+    /**
+     * Give this Session's write lock back (ADR 0024 D7).
+     *
+     * `released: false` means this client did not hold it — idempotent, not an
+     * error, so a caller releasing on teardown does not have to know whether it had
+     * already lost the lock to a takeover. Same capability fallback as
+     * {@link claim}: nothing goes on the wire to a Core with no lock table, and
+     * `supported: false` says there was never a lock to give back.
+     */
+    release(taskId: string): Promise<{
+        supported: boolean;
+        released: boolean;
+    }>;
+    /**
+     * Take this Session's write lock whoever holds it (ADR 0024 D7).
+     *
+     * The answer to a hung client, and the reason the lock needs no idle timeout.
+     * Unrecoverable by design: the previous holder's in-flight keystrokes are gone
+     * and its next mutation is refused. `takenFrom` names who lost it so a caller
+     * can say so rather than infer it — taking an unheld Session is an ordinary
+     * claim by another name.
+     *
+     * Same capability fallback as {@link claim}, answering `takenFrom: "nobody"`:
+     * there was nobody to take it from, because there is no lock on such a Core to
+     * take.
+     */
+    forceTakeover(taskId: string): Promise<{
+        supported: boolean;
+        takenFrom: CoreLinkSessionTakenFrom;
+    }>;
+    /**
+     * List every project on this Core as a live snapshot. The Core is the source of
+     * truth; a client holds none. The returned `path` is a machine path on the
+     * Core — only the Core can validate it.
+     */
+    projectsList(): Promise<CoreLinkProjectSnapshot[]>;
+    /**
+     * List every active (non-archived) task on this Core, optionally filtered to
+     * one project.
+     *
+     * `archivedCount` is how many archived rows the same scope holds — a scalar,
+     * never the rows (ADR 0019). Use {@link archivedTasksList} for those.
+     */
+    tasksList(projectId?: string): Promise<{
+        tasks: CoreLinkTaskSnapshot[];
+        archivedCount: number;
+    }>;
+    /**
+     * List every archived task on this Core, optionally filtered to one project
+     * (ADR 0019) — a separate frame from {@link tasksList}, so an active answer
+     * stays free of archived rows by construction rather than by what a caller
+     * remembers to pass.
+     */
+    archivedTasksList(projectId?: string): Promise<CoreLinkTaskSnapshot[]>;
+    /**
+     * Create / rename / archive a project on this Core. The Core validates the
+     * machine path server-side; an invalid path comes back as an `error` frame that
+     * rejects this promise. Returns `null` when a `rename`/`archive` targets a
+     * missing row.
+     */
+    projectsMutate(mutation: CoreLinkProjectMutation): Promise<CoreLinkProjectSnapshot | null>;
+    /** Create / update / delete a task. Returns `null` when it targets a missing row. */
+    tasksMutate(mutation: CoreLinkTaskMutation): Promise<CoreLinkTaskSnapshot | null>;
+    /**
+     * List every active session on this Core (optionally filtered to one project).
+     * A session's `ptyId` is set when the Core has a live PTY for that task — which
+     * is how a client knows what it can reattach to.
+     */
+    sessionsList(projectId?: string): Promise<CoreLinkSessionSnapshot[]>;
+    /**
+     * Snapshot of this Core's CLI availability. Live updates arrive as
+     * `agents:availabilityChanged` events on {@link onEvent}; this is how a client
+     * hydrates without waiting for the next probe tick.
+     */
+    agentsAvailabilityList(): Promise<CoreLinkHarnessAvailabilityMap>;
+}
+/**
+ * Turn a response frame into the value the typed methods promise, or throw the
+ * failure it carries. The two failure frames (`spawnError`, `error`) become
+ * rejections here so a caller of `spawn()` sees an exception rather than a frame
+ * it has to inspect; {@link CoreClient.request} bypasses this and hands the frame
+ * over untouched.
+ */
+export declare function unwrapResponse(msg: CoreLinkResponseFrame): unknown;
+export {};
+//# sourceMappingURL=core-client.d.ts.map

package/dist/core-client.d.ts.map

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