@byok-sdk/client 0.10.2 → 0.12.0

package/dist/daemon/auth-manager.d.ts

@@ -9,6 +9,15 @@ import type { DeviceCredentialStore, InMemoryDeviceCredentialStore } from './dev
 export declare class DeviceRevokedError extends Error {
     constructor(message?: string);
 }
+/**
+ * Thrown when the local AuthManager deadline or shutdown cancels its own
+ * in-flight request. This is deliberately distinct from `DeviceRevokedError`:
+ * only an actual challenge/token HTTP 401 is server authority for revocation.
+ */
+export declare class AuthRequestAbortedError extends Error {
+    readonly reason: 'deadline' | 'stopped';
+    constructor(reason: 'deadline' | 'stopped');
+}
 export interface AuthManagerOptions {
     serverUrl: string;
     store: DeviceStore;
@@ -23,6 +32,8 @@ export interface AuthManagerOptions {
      * permission to supersede this machine's prior active device rows.
      */
     machineId?: () => Promise<string | undefined>;
+    /** Upper bound for one pair/challenge/token fetch plus its response-body read. */
+    authRequestDeadlineMs?: number;
     /** Called once revocation is detected, so a caller (ConnectionManager) can stop retrying and surface the state instead of looping. */
     onRevoked?: () => void;
 }
@@ -42,7 +53,10 @@ export declare class AuthManager {
     private stopped;
     private pairing;
     private credentialMutationTail;
+    /** The sole cancellation authority for the request currently inside the serialized credential mutation. */
+    private activeRequest;
     private readonly credentials;
+    private readonly requestDeadlineMs;
     constructor(opts: AuthManagerOptions);
     get deviceId(): string | undefined;
     isRevoked(): boolean;
@@ -62,6 +76,12 @@ export declare class AuthManager {
     /** Always throws — `never` return type lets call sites use `if (x === 401) this.markRevoked();` without an explicit `return`/`throw` of their own. */
     private markRevoked;
     private scheduleProactiveRenewal;
+    /**
+     * Bounds one complete auth exchange rather than fetch alone. Keeping the
+     * controller active through `json()`/`text()` makes a non-cooperative or
+     * partial response body cancellable by the same authority that owns fetch.
+     */
+    private runRequest;
     private runCredentialMutation;
     /** Read the current paired authority afresh; metadata without its OS secret is re-pair required. */
     private loadRecord;

package/dist/daemon/blob-client.d.ts

@@ -1,9 +1,25 @@
 import type { BlobRef } from '@byok-sdk/protocol';
 import type { AuthManager } from './auth-manager';
+export type BlobRequestAbortReason = 'deadline' | 'cancelled';
+/** A blob request/body read did not complete before its deadline or its owner cancelled it. */
+export declare class BlobRequestAbortedError extends Error {
+    readonly reason: BlobRequestAbortReason;
+    constructor(reason: BlobRequestAbortReason);
+}
+export interface BlobClientOptions {
+    /** Bound for each individual HTTP request and response-body read. Default: 15 seconds. */
+    requestDeadlineMs?: number;
+    /** Daemon lifecycle authority; aborting it stops all in-flight blob I/O. */
+    signal?: AbortSignal;
+}
+export interface BlobRequestOptions {
+    /** Task lifecycle authority; aborting it stops this transfer before finalization. */
+    signal?: AbortSignal;
+}
 /** Seam `TaskRunner` depends on, so tests can substitute a fake without spinning up real HTTP endpoints. */
 export interface BlobResolver {
-    resolveInstruction(blobRef: BlobRef): Promise<string>;
-    uploadArtifact(content: string | Uint8Array, contentType: string, options?: {
+    resolveInstruction(blobRef: BlobRef, options?: BlobRequestOptions): Promise<string>;
+    uploadArtifact(content: string | Uint8Array, contentType: string, options?: BlobRequestOptions & {
         readonly idempotencyKey?: string;
     }): Promise<BlobRef>;
 }
@@ -16,11 +32,13 @@ export declare class BlobClient implements BlobResolver {
     #private;
     private readonly serverUrl;
     private readonly auth;
-    constructor(serverUrl: string, auth: AuthManager);
+    private readonly options;
+    private readonly requestDeadlineMs;
+    constructor(serverUrl: string, auth: AuthManager, options?: BlobClientOptions);
     /** `blobRef` -> `GET /byok/blobs/:id/url` -> fetch the presigned download URL -> text content. Always resolves fresh rather than trusting any inlined `BlobRef.url`, per docs/protocol.md §7. */
-    resolveInstruction(blobRef: BlobRef): Promise<string>;
-    /** `POST /byok/blobs` (declares size/contentType/contentHash) -> PUT the bytes to the presigned upload URL -> a `BlobRef` for `task.artifact.blobRef`. */
-    uploadArtifact(content: string | Uint8Array, contentType: string, options?: {
+    resolveInstruction(blobRef: BlobRef, options?: BlobRequestOptions): Promise<string>;
+    /** `POST /byok/blobs` -> PUT the bytes to the presigned URL -> finalize into a `BlobRef`. */
+    uploadArtifact(content: string | Uint8Array, contentType: string, options?: BlobRequestOptions & {
         readonly idempotencyKey?: string;
     }): Promise<BlobRef>;
 }

package/dist/daemon/connection-manager.d.ts

@@ -2,8 +2,10 @@ import { type CapabilityFlag, type Envelope, type RuntimeInfo, type ToolsetId }
 import { AuthManager } from './auth-manager';
 import type { CursorStore } from './cursor-store';
 import { type FleetJitter } from './deterministic-jitter';
+import { ReplayCursorTooOldError } from './replay-cursor';
 import { type BackoffOptions, type ConnectionState, type LivenessOptions } from './ws-transport';
 export type { ConnectionState } from './ws-transport';
+export { ReplayCursorTooOldError } from './replay-cursor';
 export interface ConnectionManagerOptions {
     serverUrl: string;
     deviceId: string;
@@ -35,6 +37,7 @@ export interface ConnectionManagerOptions {
     longPollIdleDelayMs?: number;
     fleetJitter?: FleetJitter;
     onOperationalOutcome?: (outcome: 'success' | 'failure', source: 'reconnect' | 'upload') => void;
+    onTerminalError?: (error: ReplayCursorTooOldError) => void;
 }
 /**
  * Owns the daemon's one logical connection to the server, which may be
@@ -119,6 +122,7 @@ export declare class ConnectionManager {
     private draining;
     private stopped;
     private revoked;
+    private terminalError;
     private settledWaiters;
     private pendingCursorSave;
     /**
@@ -249,6 +253,8 @@ export declare class ConnectionManager {
      * advertisement, and cleared across disconnect/switch boundaries.
      */
     getServerCapabilities(): readonly string[];
+    getTerminalError(): ReplayCursorTooOldError | undefined;
+    getMode(): 'ws' | 'long-poll';
     isConnected(): boolean;
     isRevoked(): boolean;
     /**
@@ -496,6 +502,7 @@ export declare class ConnectionManager {
     private onWsOutcome;
     private notifySettled;
     private enterLongPoll;
+    private enterReplayCursorTooOld;
     private exitLongPoll;
     private scheduleWsProbe;
     private enterRevoked;

package/dist/daemon/control-protocol.d.ts

@@ -422,3 +422,41 @@ export interface ShutdownParams {
     reason?: ShutdownReason;
 }
 export declare function parseShutdownParams(value: unknown): ShutdownParams;
+export interface TeamWorkspaceCreateParams {
+    workspaceId: string;
+    members: string[];
+    limits: {
+        maxMembers: number;
+        maxMessages: number;
+        maxBytes: number;
+    };
+}
+export interface TeamWorkspaceJoinParams {
+    workspaceId: string;
+    memberId: string;
+    ttlMs?: number;
+}
+export interface TeamContextParams {
+    context: string;
+}
+export interface TeamMessagePostParams extends TeamContextParams {
+    body: string;
+    contentType?: string;
+}
+export interface TeamMessageReadParams extends TeamContextParams {
+    afterSeq?: number;
+}
+export interface TeamMessageAckParams extends TeamContextParams {
+    throughSeq: number;
+}
+export interface TeamMessageInspectParams {
+    workspaceId: string;
+    afterSeq?: number;
+}
+export declare function parseTeamWorkspaceCreateParams(value: unknown): TeamWorkspaceCreateParams | undefined;
+export declare function parseTeamWorkspaceJoinParams(value: unknown): TeamWorkspaceJoinParams | undefined;
+export declare function parseTeamContextParams(value: unknown): TeamContextParams | undefined;
+export declare function parseTeamMessagePostParams(value: unknown): TeamMessagePostParams | undefined;
+export declare function parseTeamMessageReadParams(value: unknown): TeamMessageReadParams | undefined;
+export declare function parseTeamMessageAckParams(value: unknown): TeamMessageAckParams | undefined;
+export declare function parseTeamMessageInspectParams(value: unknown): TeamMessageInspectParams | undefined;

package/dist/daemon/create-daemon.d.ts

@@ -18,6 +18,7 @@ import { type ProgressBatcherOptions } from './progress-batcher';
 import { type AgentEgressReliableAppendResult } from './agent-egress-controller';
 import { type AgentEgressStatus } from './agent-egress-policy';
 import { type AgentEgressSanitizer } from './agent-egress-sanitizer';
+import { type SdkHelperHostConfig } from '../sdk-reserved-helper-host';
 import { type AgentMemoryHostedProjection } from './agent-memory';
 import type { AgentMemoryFilesystemHelperConfig } from './agent-memory-filesystem';
 import { type AgentContentReadRoot } from './agent-content-read';
@@ -90,6 +91,8 @@ export interface DaemonConfig {
     productName: string;
     productId: string;
     serverUrl: string;
+    /** Bounds one AuthManager pair/challenge/token exchange, including response-body reads. */
+    authRequestDeadlineMs?: number;
     deviceName?: string;
     /**
      * Optional override for the client-hashed physical machine identity sent
@@ -118,6 +121,12 @@ export interface DaemonConfig {
      * 2 on macOS. Windows remains fail-closed pending its native race proof.
      */
     agentMemoryFilesystem?: AgentMemoryFilesystemHelperConfig;
+    /**
+     * Explicit composition for SDK-reserved MCP helpers when this daemon is
+     * embedded in a single-file/SEA product executable. The product entrypoint
+     * must also call `runSdkReservedHelperCommand()` before its own CLI parser.
+     */
+    sdkHelperHost?: SdkHelperHostConfig;
     /**
      * Refuse legacy task offers locally. This is an additive capability only
      * after the SDK-owned Agent home has passed construction-time preflight.

package/dist/daemon/device-credential-store.d.ts

@@ -16,6 +16,18 @@ export interface DeviceMetadata {
  * from one pairing response with metadata from another.
  */
 export type DeviceRecord = DeviceMetadata & DeviceCredentials;
+/**
+ * The one durable authority allowed before a first pairing response is
+ * received. It keeps the generated key immutable across a lost response, so
+ * an exact server-side retry can prove the same public-key binding.
+ */
+export interface FirstPairingAttempt {
+    readonly kind: 'first-pairing-attempt-v1';
+    readonly deviceName: string;
+    readonly devicePublicKey: string;
+    readonly devicePrivateKeyPem: string;
+    readonly machineId?: string;
+}
 export interface DeviceCommandResult {
     readonly exitCode: number;
     readonly stdout: string;
@@ -44,6 +56,8 @@ export declare class DeviceCredentialStore {
     #private;
     constructor(options: DeviceCredentialStoreOptions);
     read(): Promise<DeviceRecord | undefined>;
+    readFirstPairingAttempt(): Promise<FirstPairingAttempt | undefined>;
+    saveFirstPairingAttempt(attempt: FirstPairingAttempt): Promise<void>;
     replace(record: DeviceRecord): Promise<void>;
     /** Returns true only after the sole secret authority is confirmed absent. */
     clear(): Promise<boolean>;
@@ -52,6 +66,8 @@ export declare class DeviceCredentialStore {
 export declare class InMemoryDeviceCredentialStore {
     #private;
     read(): Promise<DeviceRecord | undefined>;
+    readFirstPairingAttempt(): Promise<FirstPairingAttempt | undefined>;
+    saveFirstPairingAttempt(attempt: FirstPairingAttempt): Promise<void>;
     replace(record: DeviceRecord): Promise<void>;
     clear(): Promise<boolean>;
 }

package/dist/daemon/long-poll-transport.d.ts

@@ -1,5 +1,6 @@
 import { type Envelope } from '@byok-sdk/protocol';
 import { AuthManager } from './auth-manager';
+import { ReplayCursorTooOldError } from './replay-cursor';
 import { type TransportEndpoint } from './url';
 /**
  * A long-poll request failed in a way that today told the caller only
@@ -41,6 +42,8 @@ export interface LongPollClientOptions {
     onServerCapabilities?: (capabilities: string[]) => void;
     /** Called once the device is found to be revoked (401 surfaced through {@link AuthManager}) — the loop stops itself rather than retrying. */
     onRevoked?: () => void;
+    /** Called when the server cannot replay the durable cursor supplied to this poll. */
+    onReplayCursorTooOld?: (error: ReplayCursorTooOldError) => void;
     /**
      * M4 Phase 4 (version-negotiation drill fix), scope narrowed by finding F1:
      * called ONLY for a batch entry that failed to parse because its `type`

package/dist/daemon/mcp-tools-probe.d.ts

@@ -0,0 +1,105 @@
+import type { McpStdioServerConfig } from '../types';
+export declare const MCP_TOOLS_PROBE_TIMEOUT_MS = 10000;
+/**
+ * Hard cap on the bytes one probed server may write to stdout before its
+ * `tools/list` answer is complete. The probe reads a fixed two-message
+ * handshake, so a server still streaming past this is either broken or
+ * hostile; either way it must not be able to grow the daemon's heap while an
+ * offer waits on admission. Exceeding it is a probe failure, never a partial
+ * observation.
+ */
+export declare const MCP_TOOLS_PROBE_MAX_STDOUT_BYTES = 1048576;
+/**
+ * The single admission budget for observing ALL of one task's projected
+ * toolset servers, however many there are.
+ *
+ * `handleOffer` runs inside its connection's FIFO, so anything it awaits also
+ * delays the `task.cancel` / `task.approve` / next-offer envelopes queued
+ * behind it. Probing a toolset's servers one after another would multiply the
+ * per-server timeout by the server count — a device configured to the current
+ * ceiling (16 toolsets × 16 servers) could hold the control channel for
+ * minutes on a single unresponsive command. The runner therefore starts every
+ * probe at once and gives each one this same deadline, so total admission
+ * latency is bounded by one timeout regardless of server count, and each probe
+ * still kills its own child when the deadline expires.
+ */
+export declare const MCP_TOOLSET_PROBE_ADMISSION_TIMEOUT_MS = 10000;
+/**
+ * Tool names an adapter is allowed to pre-grant must be OBSERVED, never
+ * configured: the daemon's own `mcpToolsets` config carries `command`/`args`
+ * only (see `toolset-registry.ts`), so the single authority for "which tools
+ * does this server actually expose" is the server's own `tools/list` answer.
+ *
+ * A name that survives this filter is about to be interpolated into runtime
+ * CLI authority — `--allowedTools mcp__<server>__<tool>` for claude, and
+ * `mcp_servers.<server>.tools.<tool>.approval_mode` for codex. A comma, a
+ * dot, a quote, or whitespace in a tool name would forge additional grants or
+ * a different config key out of one legitimate one.
+ *
+ * A server that reports ANY name outside this shape fails the whole probe —
+ * the observation is rejected, and the task is declined permanently rather
+ * than partially granted. Granting the well-formed subset and silently
+ * dropping the rest would hand the model a toolset it can only half call, and
+ * would let one bad name ride along with good ones; only observed, validated
+ * names are ever granted, and a list that cannot be validated in full yields
+ * no grant at all. The shape is deliberately narrower than MCP's own
+ * (unbounded) name rule: the two real servers this SDK ships and every toolset
+ * server observed so far satisfy it, and a legitimate server that does not can
+ * still be listed and called by a runtime that grants tools itself — it simply
+ * cannot be pre-granted here, and this SDK will not admit a task for it.
+ */
+export declare const GRANTABLE_TOOL_NAME: RegExp;
+/**
+ * The same rule for the SERVER half of the identifier, enforced at grant
+ * resolution (`../adapters/mcp-tool-grants.ts`). A projected server name is
+ * interpolated into `mcp__<server>__<tool>` for claude and into the flat TOML
+ * key `mcp_servers.<server>.tools.<tool>.approval_mode` for codex: a `.` would
+ * split that key into a different table, and a quote, comma, or space would
+ * forge a second grant out of one. `toolset-registry.ts` already validates
+ * configured server names, so this is the second, local gate that keeps the
+ * grant surface honest for a server that reached an adapter some other way.
+ */
+export declare const GRANTABLE_MCP_SERVER_NAME: RegExp;
+/**
+ * A probe failure caused by the server's own ANSWER rather than by its
+ * environment — an ungrantable tool name, a malformed tool entry, or an
+ * oversized stream. Retrying cannot change it: the same configured command
+ * reports the same names next time. Callers use this to decline the task
+ * permanently instead of re-offering it forever (see `task-runner.ts`).
+ */
+export declare class McpToolsProbeAuthorityError extends Error {
+    constructor(message: string);
+}
+export interface McpToolsProbeOptions {
+    /** Prefix used in every error message, so a failure names the thing that failed. */
+    label?: string;
+    timeoutMs?: number;
+    /**
+     * The exact base environment the RUNTIME child of this task receives
+     * (`buildRuntimeEnv`, `./environment.ts`) — never `process.env`. The probe
+     * spawns a host-configured command, so it must not become the one place the
+     * daemon's own ambient credentials (an `AWS_SECRET_ACCESS_KEY` or
+     * `DATABASE_URL` set for the daemon's own deployment, this SDK's own
+     * `BYOK_*` control-plane variables) reach a server the real runtime path
+     * would have filtered out. Required, deliberately: a caller that forgets it
+     * fails to compile rather than silently reinstating the blanket passthrough.
+     */
+    env: Readonly<Record<string, string>>;
+    /**
+     * Working directory for the probed child — the same directory the runtime
+     * CLI is spawned in, so a server resolving relative paths sees what it will
+     * see for real. Omitted only when no such directory is resolved before
+     * admission.
+     */
+    cwd?: string;
+}
+/**
+ * Start the exact configured stdio MCP server, complete an
+ * `initialize` + `tools/list` handshake, and return the reported tool names.
+ * No `tools/call` is ever sent, so an authenticated task binding stays unused
+ * until the real runtime invokes it.
+ *
+ * The child is always killed before this resolves — the probe proves the
+ * server can start and enumerate its tools; the runtime spawns its own copy.
+ */
+export declare function probeMcpServerTools(server: Readonly<McpStdioServerConfig>, options: McpToolsProbeOptions): Promise<readonly string[]>;

package/dist/daemon/replay-cursor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The server retained no contiguous replay history after the cursor the
+ * daemon acknowledged. This is terminal for the current device enrollment:
+ * retrying the same cursor can only repeat the loss condition.
+ */
+export declare class ReplayCursorTooOldError extends Error {
+    readonly recoverableFrom?: number | undefined;
+    constructor(recoverableFrom?: number | undefined);
+}

package/dist/daemon/resolve-agent-memory-mcp-bin.d.ts

@@ -1,6 +1,7 @@
+import { type SdkHelperHostConfig } from '../sdk-reserved-helper-host';
 export interface ResolvedAgentMemoryMcpBin {
     readonly command: string;
     readonly args: readonly string[];
 }
 /** Resolve the SDK-owned stdio Agent-memory MCP helper shipped beside the client bundle. */
-export declare function resolveAgentMemoryMcpBin(externalHelperConfigured?: boolean): ResolvedAgentMemoryMcpBin | undefined;
+export declare function resolveAgentMemoryMcpBin(externalHelperConfigured?: boolean, host?: SdkHelperHostConfig): ResolvedAgentMemoryMcpBin | undefined;

package/dist/daemon/resolve-agent-message-mcp-bin.d.ts

@@ -1,6 +1,7 @@
+import { type SdkHelperHostConfig } from '../sdk-reserved-helper-host';
 export interface ResolvedAgentMessageMcpBin {
     readonly command: string;
     readonly args: readonly string[];
 }
 /** Resolve the SDK-owned stdio MCP helper shipped beside the client bundle. */
-export declare function resolveAgentMessageMcpBin(): ResolvedAgentMessageMcpBin;
+export declare function resolveAgentMessageMcpBin(host?: SdkHelperHostConfig): ResolvedAgentMessageMcpBin;

package/dist/daemon/task-runner.d.ts

@@ -1,5 +1,5 @@
 import { type AgentMessageContentType, type AgentEgressPolicy, type Envelope, type PermissionPolicy, type RuntimeId, type TerminalProjectionSelection, type TaskOfferPayload, type TaskOfferForAgentPayload, type TaskOfferForAgentWithEgressPayload, type TaskOfferForAgentWithEgressFreshPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
-import { type McpToolsetConfig, type RuntimeAdapter } from '../types';
+import { type McpStdioServerConfig, type McpToolsetConfig, type RuntimeAdapter } from '../types';
 import { AgentHomeManager, type AgentRef } from '../agent-home';
 import { AgentSessionHandoffStore, type AgentTerminalCause } from './agent-session-handoff-store';
 import { type RuntimeDisposalStage } from '../runtime-failure';
@@ -12,6 +12,7 @@ import type { SessionWorkspaceStore } from './session-workspace-store';
 import type { GitWorkspaceManager, GitWorkspaceObservation } from './git-workspace';
 import type { GitWorkspaceStore, GitWorkspacePhase } from './git-workspace-store';
 import type { AgentEgressController } from './agent-egress-controller';
+import { type McpToolsProbeOptions } from './mcp-tools-probe';
 import type { ResolvedAgentMessageMcpBin } from './resolve-agent-message-mcp-bin';
 import type { ResolvedAgentMemoryMcpBin } from './resolve-agent-memory-mcp-bin';
 import { type AgentMemoryAuditWarning, type AgentMemoryHostedProjection } from './agent-memory';
@@ -369,6 +370,22 @@ export interface TaskRunnerDeps {
     };
     /** SDK-owned, task-scoped MCP helper. Required only for offers declaring messageEgress. */
     agentMessageMcpBin?: Readonly<ResolvedAgentMessageMcpBin>;
+    /**
+     * Production pre-runtime executability/handshake gate for the exact message
+     * helper config. `env` is the same allowlisted child environment the runtime
+     * gets (`buildRuntimeEnv`), and `cwd` the same working directory, so the
+     * helper is proved under the conditions it will actually run in.
+     */
+    agentMessageMcpPreflight?: (server: Readonly<McpStdioServerConfig>, env: Readonly<Record<string, string>>, cwd?: string) => Promise<void>;
+    /**
+     * Override the `tools/list` observation of a projected toolset MCP server.
+     * Defaults to the real handshake (`mcp-tools-probe.ts`); tests substitute a
+     * stub. It is deliberately NOT optional-with-no-default the way
+     * `agentMessageMcpPreflight` is: an adapter may only grant tool names that
+     * were observed, so a runner with no observation at all would silently
+     * project toolsets the model can list and never call.
+     */
+    mcpToolsetToolsProbe?: (server: Readonly<McpStdioServerConfig>, options: McpToolsProbeOptions) => Promise<readonly string[]>;
     /** SDK-owned MCP helper injected only into strict Agent tasks. */
     agentMemoryMcpBin?: Readonly<ResolvedAgentMemoryMcpBin>;
     /** Explicit external secure-fs helper. No PATH discovery or bundled native addon exists. */
@@ -404,6 +421,7 @@ export declare class TaskRunner {
     private readonly deps;
     private readonly tasks;
     private readonly pendingMessageTasks;
+    private readonly messageOutboxesByHome;
     private readonly messageContextByToken;
     private readonly messageContextByTask;
     private readonly memoryContextByToken;
@@ -464,6 +482,8 @@ export declare class TaskRunner {
      * costs nothing.
      */
     private readonly inFlightOffers;
+    /** Blob I/O before an offer becomes an active task still belongs to that offer's cancellation authority. */
+    private readonly inFlightBlobAborts;
     /**
      * Finding P2 (Fix 2c): taskIds that have reached a terminal outcome
      * (Complete/Failed/Cancelled) this session — populated in `finish()`.
@@ -575,6 +595,7 @@ export declare class TaskRunner {
     }>;
     /** Restore activated, unaccepted message drafts before transport admission on daemon restart. */
     recoverAgentMessageOutboxes(agentsRoot: string): Promise<void>;
+    private agentMessageOutbox;
     /** Retry stable recovered records after a transport handshake/re-handshake. */
     retryRecoveredAgentMessages(): void;
     private sendAgentMessageRecord;

package/dist/daemon/team-workspace.d.ts

@@ -0,0 +1,202 @@
+/**
+ * The local team channel is deliberately a small, versioned contract.  It is
+ * not a task outbox and it has no cloud or runtime authority.  The state file
+ * is an atomic envelope so a post, a receipt, or a membership change is
+ * either wholly visible after a restart or not visible at all.
+ */
+export declare const TEAM_WORKSPACE_VERSION: 1;
+export declare const TEAM_WORKSPACE_DIRECTORY: string;
+export declare const TEAM_WORKSPACE_STATE_FILENAME = "state.json";
+export declare const TEAM_WORKSPACE_DEFAULT_CONTENT_TYPE = "text/plain";
+/** Bounds are intentionally smaller than the control protocol's 64 KiB line. */
+export declare const TEAM_WORKSPACE_MAX_ID_BYTES = 128;
+export declare const TEAM_WORKSPACE_MAX_BODY_BYTES: number;
+export declare const TEAM_WORKSPACE_MAX_CONTENT_TYPE_BYTES = 128;
+export declare const TEAM_WORKSPACE_MAX_MEMBERS = 256;
+export declare const TEAM_WORKSPACE_MAX_MESSAGES = 100000;
+export declare const TEAM_WORKSPACE_MAX_BYTES: number;
+export declare const TEAM_WORKSPACE_DEFAULT_LEASE_TTL_MS: number;
+export declare const TEAM_WORKSPACE_MIN_LEASE_TTL_MS = 1;
+export declare const TEAM_WORKSPACE_MAX_LEASE_TTL_MS: number;
+/** A stable, content-addressed registry revision. */
+export type TeamWorkspaceRevision = `sha256:${string}`;
+export interface TeamWorkspaceLimits {
+    readonly maxMembers: number;
+    readonly maxMessages: number;
+    readonly maxBytes: number;
+}
+export interface TeamWorkspaceDefinition {
+    readonly version: typeof TEAM_WORKSPACE_VERSION;
+    readonly workspaceId: string;
+    readonly revision: TeamWorkspaceRevision;
+    readonly members: readonly string[];
+    readonly limits: TeamWorkspaceLimits;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface TeamWorkspaceMemberReceipt {
+    readonly workspaceId: string;
+    readonly memberId: string;
+    readonly acknowledgedThroughSeq: number;
+    readonly deliveredThroughSeq: number;
+    readonly registryRevision: TeamWorkspaceRevision;
+    readonly updatedAt: string;
+}
+export interface TeamMessage {
+    readonly version: typeof TEAM_WORKSPACE_VERSION;
+    readonly workspaceId: string;
+    readonly seq: number;
+    readonly messageId: string;
+    readonly senderMemberId: string;
+    readonly body: string;
+    readonly contentType: string;
+    readonly byteCount: number;
+    readonly contentHash: TeamWorkspaceRevision;
+    readonly createdAt: string;
+}
+/**
+ * The token is intentionally opaque to callers.  It is returned once from
+ * lease issuance and only its digest is persisted; raw bearer material never
+ * enters the durable state file.
+ */
+export interface TeamMemberLease {
+    readonly opaqueToken: string;
+    readonly workspaceId: string;
+    readonly memberId: string;
+    readonly registryRevision: TeamWorkspaceRevision;
+    readonly expiresAt: string;
+}
+export interface CreateTeamWorkspaceInput {
+    readonly workspaceId: string;
+    readonly members: readonly string[];
+    readonly limits: TeamWorkspaceLimits;
+}
+export interface UpdateTeamWorkspaceInput {
+    readonly workspaceId: string;
+    readonly expectedRevision: TeamWorkspaceRevision;
+    readonly members: readonly string[];
+    readonly limits?: TeamWorkspaceLimits;
+}
+export interface CreateTeamMemberLeaseInput {
+    readonly workspaceId: string;
+    readonly memberId: string;
+    readonly ttlMs?: number;
+}
+export interface TeamPostMessageInput {
+    readonly lease: TeamMemberLease;
+    readonly body: string;
+    readonly contentType?: string;
+}
+export interface TeamReadMessagesInput {
+    readonly lease: TeamMemberLease;
+    readonly afterSeq?: number;
+}
+export interface TeamAckMessagesInput {
+    readonly lease: TeamMemberLease;
+    readonly throughSeq: number;
+}
+export interface TeamMessageAcceptedReceipt {
+    readonly accepted: true;
+    readonly durable: true;
+    readonly workspaceId: string;
+    readonly memberId: string;
+    readonly seq: number;
+    readonly messageId: string;
+    readonly message: TeamMessage;
+}
+export interface TeamReadMessagesResult {
+    readonly workspaceId: string;
+    readonly memberId: string;
+    readonly messages: readonly TeamMessage[];
+    readonly afterSeq: number;
+    readonly deliveredThroughSeq: number;
+    readonly receipt: TeamWorkspaceMemberReceipt;
+}
+export interface TeamAckReceipt {
+    readonly accepted: true;
+    readonly durable: true;
+    readonly throughSeq: number;
+    readonly receipt: TeamWorkspaceMemberReceipt;
+}
+export interface LocalTeamWorkspaceOptions {
+    /** Test seam for deterministic lease expiry and timestamps. */
+    readonly now?: () => number;
+}
+/** Common typed failure for all rejected local team operations. */
+export declare class TeamWorkspaceError extends Error {
+    constructor(message: string);
+}
+export declare class TeamWorkspaceValidationError extends TeamWorkspaceError {
+    constructor(message: string);
+}
+export declare class TeamWorkspaceNotFoundError extends TeamWorkspaceError {
+    readonly workspaceId: string;
+    constructor(workspaceId: string);
+}
+export declare class TeamWorkspaceConflictError extends TeamWorkspaceError {
+    constructor(message: string);
+}
+export declare class TeamWorkspaceQuotaError extends TeamWorkspaceError {
+    readonly quota: 'members' | 'messages' | 'bytes';
+    constructor(quota: 'members' | 'messages' | 'bytes', message: string);
+}
+export declare class TeamWorkspaceLeaseError extends TeamWorkspaceError {
+    constructor(message: string);
+}
+export declare class TeamWorkspaceReceiptError extends TeamWorkspaceError {
+    constructor(message: string);
+}
+export declare class TeamWorkspaceCorruptError extends TeamWorkspaceError {
+    constructor(message: string);
+}
+/** Public fail-closed validators for control/MCP composition sites. */
+export declare function validateTeamWorkspaceId(value: unknown): string;
+export declare function validateTeamMemberId(value: unknown): string;
+export declare function validateTeamMessageBody(value: unknown): string;
+export declare function validateTeamContentType(value: unknown): string;
+/** Encode the full lease as one opaque helper context; it is never model input. */
+export declare function encodeTeamMemberContext(lease: TeamMemberLease): string;
+/** Decode only the exact bounded lease shape emitted by {@link encodeTeamMemberContext}. */
+export declare function decodeTeamMemberContext(value: unknown): TeamMemberLease;
+/**
+ * Local-only durable TeamWorkspace authority.  The service is intentionally
+ * independent from TaskRunner and cloud protocol: a caller must first obtain
+ * a member lease, and all message operations derive workspace/member identity
+ * from that lease rather than accepting it from model input.
+ */
+export declare class LocalTeamWorkspace {
+    private readonly rootDir;
+    private readonly statePath;
+    private readonly now;
+    private readonly queueKey;
+    constructor(storeDir: string, options?: LocalTeamWorkspaceOptions);
+    /** Create the secure state directory; it is safe to call on every start. */
+    initialize(): Promise<void>;
+    createWorkspace(input: CreateTeamWorkspaceInput): Promise<TeamWorkspaceDefinition>;
+    getWorkspace(workspaceId: string): Promise<TeamWorkspaceDefinition | undefined>;
+    listWorkspaces(): Promise<readonly TeamWorkspaceDefinition[]>;
+    /** Local operator read for the tmux pane; it does not create or advance a member receipt. */
+    inspectMessages(workspaceId: string, afterSeq?: number): Promise<readonly TeamMessage[]>;
+    /** CAS-guarded membership/limit update.  A revision change invalidates all leases. */
+    updateWorkspace(input: UpdateTeamWorkspaceInput): Promise<TeamWorkspaceDefinition>;
+    createMemberLease(input: CreateTeamMemberLeaseInput): Promise<TeamMemberLease>;
+    revokeMemberLease(input: {
+        readonly lease: TeamMemberLease;
+    }): Promise<void>;
+    /** Validate the opaque lease and return its daemon-owned identity. */
+    validateMemberLease(lease: TeamMemberLease): Promise<Readonly<{
+        workspaceId: string;
+        memberId: string;
+        registryRevision: TeamWorkspaceRevision;
+        expiresAt: string;
+    }>>;
+    postMessage(input: TeamPostMessageInput): Promise<TeamMessageAcceptedReceipt>;
+    readMessages(input: TeamReadMessagesInput): Promise<TeamReadMessagesResult>;
+    ackMessages(input: TeamAckMessagesInput): Promise<TeamAckReceipt>;
+    private resolveLease;
+    private load;
+    private save;
+    private enqueue;
+}
+/** The longer name is useful at composition sites; both names denote one authority. */
+export { LocalTeamWorkspace as LocalTeamWorkspaceService };