@skaile/workspaces 0.8.5

package/dist/secrets/src/providers/local.d.ts

@@ -0,0 +1,63 @@
+/**
+ * LocalSecretsProvider — AES-256-GCM encrypted file-blob storage at `~/.skaile/secrets/`.
+ *
+ * Each secret is stored as a separate `.enc` file named by the SHA-256 hash of the ref
+ * (collision-free, filesystem-safe). A companion `.meta.json` stores the original ref,
+ * timestamps, and optional user metadata. The master key is derived via PBKDF2-SHA-512
+ * from one of three {@link KeyStrategy} sources: OS keychain (keytar), a passphrase from
+ * `SKAILE_SECRETS_PASSPHRASE`, or a machine-derived passphrase as last resort.
+ * Switching strategies re-encrypts all existing secrets with the new key.
+ *
+ * @docLink packages/secrets/concepts#local-secrets-provider
+ */
+import type { ISecretsProvider, SecretMetadata, ProviderCapabilities, SetSecretOptions, ListFilter } from "@skaile/workspaces/plugins";
+/**
+ * Master key derivation strategy used by {@link LocalSecretsProvider}.
+ *
+ * - `keychain` — OS keychain (via keytar); most secure, requires keytar to be installed.
+ * - `passphrase` — PBKDF2 from `SKAILE_SECRETS_PASSPHRASE` env var; portable across machines.
+ * - `machine` — deterministic from hostname + username; least secure, last-resort fallback.
+ *
+ * The active strategy is persisted in `~/.skaile/secrets/.key-strategy`. Switching strategies
+ * re-encrypts all existing secrets with the new key.
+ *
+ * @docLink packages/secrets/concepts#local-secrets-provider
+ */
+export type KeyStrategy = "keychain" | "passphrase" | "machine";
+export declare class LocalSecretsProvider implements ISecretsProvider {
+    readonly id = "local";
+    private secretsDir;
+    private masterKey;
+    private salt;
+    private strategy;
+    constructor(secretsDir?: string);
+    private ensureDir;
+    private loadOrCreateSalt;
+    private ensureKey;
+    private tryKeychainStrategy;
+    private getPassphraseForStrategy;
+    /**
+     * Set the key strategy explicitly. Called by `skaile auth set-key-strategy`.
+     *
+     * When existing secrets are present, they are re-encrypted with the new key
+     * to prevent data loss from key mismatch.
+     */
+    setKeyStrategy(strategy: KeyStrategy, passphrase?: string): Promise<void>;
+    getKeyStrategy(): KeyStrategy;
+    private encFilename;
+    private metaFilename;
+    private metaPath;
+    private listEncFiles;
+    getSecret(ref: string): Promise<Uint8Array>;
+    setSecret(ref: string, value: Uint8Array, opts?: SetSecretOptions): Promise<void>;
+    deleteSecret(ref: string): Promise<void>;
+    listSecrets(filter?: ListFilter): Promise<string[]>;
+    testConnection(): Promise<{
+        ok: boolean;
+        latencyMs?: number;
+        error?: string;
+    }>;
+    getMetadata(ref: string): Promise<SecretMetadata>;
+    getCapabilities(): ProviderCapabilities;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/secrets/src/providers/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../../secrets/src/providers/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,EACX,MAAM,4BAA4B,CAAC;AAyBpC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,CAAC;AAsDhE,qBAAa,oBAAqB,YAAW,gBAAgB;IAC3D,QAAQ,CAAC,EAAE,WAAW;IACtB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,QAAQ,CAA0B;gBAE9B,UAAU,CAAC,EAAE,MAAM;IAM/B,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,gBAAgB;YAUV,SAAS;YAqBT,mBAAmB;YAgBnB,wBAAwB;IAiDtC;;;;;OAKG;IACG,cAAc,CAAC,QAAQ,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0E/E,cAAc,IAAI,WAAW;IAU7B,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,YAAY;IAOd,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAwB3C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BjF,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxC,WAAW,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAsBnD,cAAc,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAuB9E,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA2BvD,eAAe,IAAI,oBAAoB;CAQxC"}

package/dist/secrets/src/router.d.ts

@@ -0,0 +1,91 @@
+/**
+ * SecretsRouter — audit chokepoint for all secret operations.
+ *
+ * Registers {@link ISecretsProvider} implementations by id, routes credential refs by
+ * prefix or via routing config, and emits {@link CredentialAccessed} events for every
+ * get, set, delete, list, and metadata operation. Routing rules are evaluated top-to-bottom;
+ * the first matching prefix wins and falls back to the configured default provider.
+ *
+ * @docLink packages/secrets/concepts#secrets-router
+ */
+import type { ISecretsProvider, SetSecretOptions, ListFilter, SecretMetadata, ProviderCapabilities } from "@skaile/workspaces/plugins";
+/**
+ * Audit event emitted by {@link SecretsRouter} after every secret operation.
+ *
+ * Delivered synchronously to all registered {@link AuditSink} functions. Errors thrown
+ * by sinks are swallowed to ensure they never break the underlying secret operation.
+ *
+ * @docLink packages/secrets/concepts#secrets-router
+ */
+export interface CredentialAccessed {
+    credential_ref: string;
+    operation: "get" | "set" | "delete" | "list" | "metadata";
+    provider_id: string;
+    caller_session_id?: string;
+    caller_tool_call?: string;
+    timestamp: Date;
+}
+/**
+ * Callback function that receives {@link CredentialAccessed} audit events from {@link SecretsRouter}.
+ *
+ * Register sinks via `SecretsRouter.addSink()`. Sinks run synchronously after each operation;
+ * exceptions are caught and suppressed so they cannot interrupt credential resolution.
+ *
+ * @docLink packages/secrets/concepts#secrets-router
+ */
+export type AuditSink = (event: CredentialAccessed) => void;
+/**
+ * A single routing rule that maps a credential ref prefix to a provider.
+ *
+ * Rules in {@link SecretsRouterConfig.rules} are evaluated top-to-bottom;
+ * the first rule whose `prefix` matches the start of the credential ref wins.
+ *
+ * @docLink packages/secrets/concepts#secrets-router
+ */
+export interface RoutingRule {
+    /** Prefix match on credential_ref. First match wins. */
+    prefix: string;
+    /** Provider id to route to. */
+    provider_id: string;
+}
+/**
+ * Configuration object for {@link SecretsRouter}.
+ *
+ * Specifies the default provider id used when no routing rule matches, and an optional
+ * ordered list of {@link RoutingRule} entries for prefix-based routing.
+ *
+ * @docLink packages/secrets/concepts#secrets-router
+ */
+export interface SecretsRouterConfig {
+    /** Default provider id when no routing rule matches. */
+    default_provider: string;
+    /** Ordered routing rules. Evaluated top-to-bottom; first prefix match wins. */
+    rules?: RoutingRule[];
+}
+export declare class SecretsRouter {
+    private providers;
+    private config;
+    private sinks;
+    /** Caller context for audit events (set per-request by the runner). */
+    callerSessionId?: string;
+    callerToolCall?: string;
+    constructor(config: SecretsRouterConfig);
+    register(provider: ISecretsProvider): void;
+    unregister(id: string): void;
+    listProviders(): string[];
+    addSink(sink: AuditSink): void;
+    private emit;
+    private resolve;
+    getSecret(ref: string): Promise<Uint8Array>;
+    setSecret(ref: string, value: Uint8Array, opts?: SetSecretOptions): Promise<void>;
+    deleteSecret(ref: string): Promise<void>;
+    listSecrets(filter?: ListFilter): Promise<string[]>;
+    getMetadata(ref: string): Promise<SecretMetadata>;
+    getCapabilities(providerId?: string): ProviderCapabilities | null;
+    testConnection(providerId?: string): Promise<{
+        ok: boolean;
+        latencyMs?: number;
+        error?: string;
+    }>;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/secrets/src/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../secrets/src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,oBAAoB,EACrB,MAAM,4BAA4B,CAAC;AAOpC;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAM5D;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,gBAAgB,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;CACvB;AAMD,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAuC;IACxD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,KAAK,CAAmB;IAEhC,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,mBAAmB;IAMvC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAI1C,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI5B,aAAa,IAAI,MAAM,EAAE;IAMzB,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAI9B,OAAO,CAAC,IAAI;IAoBZ,OAAO,CAAC,OAAO;IAwBT,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAM3C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjF,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC,WAAW,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUnD,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAMvD,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI;IAM3D,cAAc,CAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAQhE"}

package/dist/session/index.js

@@ -0,0 +1,5 @@
+export { SessionDispatcher, isAgentAddressed, isMentioned, parseMentions } from '../chunk-44ZICIN4.js';
+import '../chunk-O5AE4QDX.js';
+import '../chunk-NSBPE2FW.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/session/src/dispatcher.d.ts

@@ -0,0 +1,246 @@
+import type { AgentClient } from "@skaile/workspaces/client";
+import type { AgentCommand, AgentEvent, ConnectorRequestCommand, ConnectorResponseEvent, Mention, ReplyRef } from "@skaile/workspaces/types";
+import type { Message, MessageStore, SubscriberTransport } from "./types.js";
+/**
+ * Construction options for {@link SessionDispatcher}.
+ *
+ * All three infrastructure objects (`client`, `store`, `transport`) are
+ * injected by the caller so the dispatcher remains testable and framework-agnostic.
+ *
+ * @docLink packages/session/api-reference#session-dispatcher
+ */
+export interface SessionDispatcherOptions {
+    /** Unique identifier for the session this dispatcher manages. */
+    sessionId: string;
+    /** Connected agent client used to send commands and receive events. */
+    client: AgentClient;
+    /** Persistence layer for all non-transient messages. */
+    store: MessageStore;
+    /** Fan-out transport for broadcasting events to connected frontends. */
+    transport: SubscriberTransport;
+    /**
+     * When true, the dispatcher prepends conversation history to every prompt
+     * command sent to the agent. Enable for agents without native session
+     * continuity (e.g. mock mode). Agents with native multi-turn support
+     * (Claude SDK, OMP) should set this to false to avoid duplicate context.
+     * Default: false.
+     */
+    injectConversationHistory?: boolean;
+    /** Max conversation history messages to include in enriched prompts (default: 50). */
+    historyLimit?: number;
+    /**
+     * Optional callback to transform prompt text before forwarding to the agent.
+     * The original (untransformed) prompt is persisted and broadcast to subscribers.
+     * Applied after conversation history enrichment. Use this to inject context
+     * (e.g. UI state) that the agent should see but subscribers should not.
+     */
+    transformPrompt?: (prompt: string, senderId: string | undefined, replyTo?: ReplyRef) => string;
+}
+/**
+ * Bridges a single agent session between an {@link AgentClient} and one or more
+ * frontend subscribers.
+ *
+ * Responsibilities:
+ * - Persists every non-transient command and event as a {@link Message} with a
+ *   monotonic sequence number via the injected {@link MessageStore}.
+ * - Fans agent events out to all connected frontends via the injected
+ *   {@link SubscriberTransport}.
+ * - Optionally enriches prompt commands with conversation history so agents
+ *   without native multi-turn support maintain context across turns.
+ *
+ * **Lifecycle:** call {@link init} before any other method, and {@link disconnect}
+ * when the session ends.
+ *
+ * @example
+ * ```ts
+ * const dispatcher = new SessionDispatcher({
+ *   sessionId: 'sess-123',
+ *   client: agentClient,
+ *   store: prismaMessageStore,
+ *   transport: trpcTransport,
+ * })
+ * await dispatcher.init()
+ * const history = await dispatcher.subscribe('ws-conn-abc', { limit: 50 })
+ * const msg = await dispatcher.sendCommand({ type: 'prompt', prompt: 'Hello' }, 'user-42')
+ * await dispatcher.disconnect()
+ * ```
+ *
+ * @docLink packages/session/api-reference#session-dispatcher
+ */
+export declare class SessionDispatcher {
+    /** The session identifier this dispatcher is bound to. */
+    readonly sessionId: string;
+    private client;
+    private store;
+    private transport;
+    private subscribers;
+    private subscriberMeta;
+    private seq;
+    private _availableResources;
+    /** Whether to inject conversation history into prompt commands. */
+    private readonly injectConversationHistory;
+    /** Maximum number of history messages to include in enriched prompts. */
+    private readonly historyLimit;
+    /** Optional prompt transformer applied before forwarding (after persistence). */
+    private _transformPrompt?;
+    /** Whether the dispatcher is currently in compaction mode. */
+    private _compacting;
+    /** Accumulated text content during compaction. */
+    private _compactionText;
+    /**
+     * @param opts - Dispatcher configuration — see {@link SessionDispatcherOptions}.
+     */
+    constructor(opts: SessionDispatcherOptions);
+    /**
+     * Replace the prompt transformer at runtime.
+     *
+     * Useful when additional context (e.g. a UI state cache) becomes available
+     * after the dispatcher is constructed but before the first prompt is sent.
+     */
+    set transformPrompt(fn: ((prompt: string, senderId: string | undefined, replyTo?: ReplyRef) => string) | undefined);
+    /**
+     * Initialize the dispatcher for this session.
+     *
+     * Restores the monotonic sequence counter from the store and wires up the
+     * agent event listener. Must be called once before any other method.
+     *
+     * @throws If {@link MessageStore.getLatestSeq} rejects.
+     */
+    init(): Promise<void>;
+    /**
+     * Register a frontend subscriber and return recent message history.
+     *
+     * Subsequent agent events are pushed to this subscriber via the
+     * {@link SubscriberTransport} until {@link unsubscribe} is called.
+     *
+     * @param subscriberId - Opaque connection ID (e.g. WebSocket session ID).
+     * @param opts - Optional subscription options.
+     * @param opts.limit - Number of recent messages to return (default: 50).
+     * @returns Recent messages ordered by seq ascending.
+     */
+    subscribe(subscriberId: string, opts?: {
+        limit?: number;
+        userId?: string;
+        roles?: string[];
+    }): Promise<Message[]>;
+    /**
+     * Remove a frontend subscriber and release transport resources.
+     *
+     * @param subscriberId - The ID passed to {@link subscribe}.
+     */
+    unsubscribe(subscriberId: string): void;
+    /**
+     * Send a command from a frontend to the agent.
+     *
+     * Persistent commands are wrapped in a Message envelope and stored before
+     * forwarding. Transient commands (resource RPC) are forwarded directly
+     * without persistence — returns null in that case.
+     *
+     * For `prompt` commands, the original message is persisted, but an enriched
+     * version (with conversation history prepended) is sent to the agent so it
+     * maintains context across turns.
+     *
+     * @param command - The command to dispatch to the agent (a prompt or tool result).
+     * @param senderId - ID of the user sending the command, if known.
+     * @param mentions - Resolved mention objects extracted from the prompt text.
+     * @param visibility - Optional platform visibility envelope (F-23).
+     * @param outgoingPrefix - Optional text prepended to the outgoing command's
+     *   user-text field ({@link command.prompt} / `command.answer` /
+     *   `command.content`) AFTER persistence but BEFORE history enrichment and
+     *   {@link transformPrompt}. The persisted {@link Message} envelope is built
+     *   from the original `command` and never sees the prefix. Use this to
+     *   inject one-shot wake-time context (Option B1 pending restoration
+     *   prompt) that the agent must see but UI subscribers must not.
+     * @returns The persisted Message envelope, or null for transient command types.
+     */
+    sendCommand(command: AgentCommand, senderId?: string, mentions?: Mention[], visibility?: NonNullable<Message["visibility"]>, outgoingPrefix?: string): Promise<Message | null>;
+    /**
+     * Persist a synthetic event (not received from the agent) and broadcast it.
+     *
+     * Used by the platform to inject events like a partial-text `finished` record
+     * before a cancel command.
+     *
+     * @param event - The agent event to persist.
+     * @param mentions - Resolved mentions from the originating command.
+     */
+    persistEvent(event: AgentEvent, mentions?: Mention[]): Promise<Message | null>;
+    /**
+     * Load paginated message history for this session.
+     *
+     * @param opts.before - Return messages with seq strictly less than this value.
+     * @param opts.limit - Maximum number of messages to return.
+     */
+    getMessages(opts?: {
+        before?: number;
+        limit?: number;
+    }): Promise<Message[]>;
+    /**
+     * Available mounts and connectors captured from the most recent
+     * `resources_available` event emitted by the agent on connect.
+     *
+     * Empty until the agent emits the event or {@link seedResources} is called.
+     */
+    get availableResources(): {
+        mounts: unknown[];
+        connectors: unknown[];
+    };
+    /**
+     * Seed the available resources from an external cache.
+     *
+     * This is needed when the dispatcher is created after the agent has already
+     * emitted `resources_available` on WebSocket connect. Without seeding, the
+     * dispatcher would report an empty resource list until the next reconnect.
+     *
+     * @param resources - Resource handles to register before the session starts.
+     */
+    seedResources(resources: {
+        mounts: unknown[];
+        connectors: unknown[];
+    }): void;
+    /**
+     * Send a resource request and await the correlated response.
+     *
+     * This is a convenience method for request/response resource RPC.
+     * The request is transient (not persisted). A one-shot event listener
+     * waits for the matching `resource_response` by `requestId`.
+     *
+     * @param command - A ConnectorRequestCommand (caller must set requestId).
+     * @param timeoutMs - How long to wait before rejecting (default: 30s).
+     */
+    requestResource(command: ConnectorRequestCommand, timeoutMs?: number): Promise<ConnectorResponseEvent>;
+    /**
+     * Broadcast a transient event to all subscribers without persisting it.
+     *
+     * Used for ephemeral signals like typing indicators or user-command
+     * echoes that other subscribers need to see in real time.
+     */
+    broadcast(event: AgentEvent): void;
+    /** Disconnect the agent client and clean up all subscribers. */
+    disconnect(): Promise<void>;
+    /**
+     * Enter compaction mode. While active, events from the agent are captured
+     * but NOT persisted. Text content is accumulated for the snapshot.
+     */
+    beginCompaction(): void;
+    /**
+     * Exit compaction mode and return the accumulated text.
+     * The caller is responsible for creating and emitting the snapshot event.
+     */
+    endCompaction(): string;
+    /** Whether the dispatcher is currently in compaction mode. */
+    get isCompacting(): boolean;
+    /**
+     * Build an enriched prompt by prepending conversation history.
+     *
+     * Loads recent persisted messages, formats user/assistant turns, and
+     * wraps them in a `<conversation_history>` block. The current user
+     * message (just persisted) is excluded since it is already the prompt.
+     *
+     * Returns the original prompt unchanged if there is no prior history.
+     */
+    private enrichPromptWithHistory;
+    private handleAgentEvent;
+    private shouldPersist;
+    private createMessage;
+}
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/session/src/dispatcher.d.ts.map

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

package/dist/session/src/index.d.ts

@@ -0,0 +1,6 @@
+export type { SessionDispatcherOptions } from "./dispatcher.js";
+export { SessionDispatcher } from "./dispatcher.js";
+export type { MentionResolver } from "./mentions.js";
+export { isAgentAddressed, isMentioned, parseMentions } from "./mentions.js";
+export type { Message, MessageStore, SubscriberInfo, SubscriberTransport } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/session/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../session/src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC7E,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/session/src/mentions.d.ts

@@ -0,0 +1,80 @@
+import type { Mention, MentionGroup } from "@skaile/workspaces/types";
+/**
+ * Re-exported from `@skaile/workspaces/types` so consumers can import mention
+ * types directly from `@skaile/workspaces/session` without a separate dependency.
+ */
+export type { Mention, MentionGroup };
+/**
+ * Consumer-provided resolver that maps @mention tokens to users and groups.
+ *
+ * The platform provides an implementation backed by Prisma and the live
+ * presence service. Tests use lightweight mocks.
+ *
+ * @example
+ * ```ts
+ * const resolver: MentionResolver = {
+ *   resolveUser: (name) => db.users.findByName(name),
+ *   resolveGroup: (group) => presence.getMemberIds(group),
+ *   getOnlineUserIds: () => presence.getOnlineIds(),
+ * }
+ * ```
+ *
+ * @docLink packages/session/api-reference#mention-resolver
+ */
+export interface MentionResolver {
+    /**
+     * Resolve a `@name` token to a user record.
+     *
+     * @param name - The token after the `@` symbol (case-insensitive lookup).
+     * @returns User record, or null if the name is not found.
+     */
+    resolveUser(name: string): {
+        userId: string;
+        name: string;
+    } | null;
+    /**
+     * Resolve a group mention token to the list of member user IDs.
+     *
+     * @param group - The well-known group name (e.g. `"agent"`, `"all"`).
+     * @returns Array of member user IDs belonging to the group.
+     */
+    resolveGroup(group: MentionGroup): string[];
+    /** Return the IDs of users currently online (used by the `here` and `humans_here` groups). */
+    getOnlineUserIds(): string[];
+}
+/**
+ * Scan `text` for @token patterns and return resolved {@link Mention} objects.
+ *
+ * - Well-known group tokens (`agent`, `humans`, `humans_here`, `here`, `all`)
+ *   are resolved via {@link MentionResolver.resolveGroup}.
+ * - All other tokens are resolved via {@link MentionResolver.resolveUser}.
+ * - Tokens that cannot be resolved are silently ignored.
+ * - Results are sorted by character offset ascending.
+ *
+ * @param text - Raw message text to scan for `@token` patterns.
+ * @param resolver - Resolver that maps tokens to users and groups.
+ * @returns Resolved mentions ordered by position in text.
+ * @docLink packages/session/api-reference#mention-resolver
+ */
+export declare function parseMentions(text: string, resolver: MentionResolver): Mention[];
+/**
+ * Returns true if `userId` is directly mentioned or is a member of any
+ * group mention's resolved list.
+ *
+ * @param userId - The user ID to check (e.g. from the auth context).
+ * @param mentions - Parsed mentions from {@link parseMentions}.
+ * @docLink packages/session/api-reference#mention-resolver
+ */
+export declare function isMentioned(userId: string, mentions: Mention[]): boolean;
+/**
+ * Returns true if the agent is addressed by any mention in the list.
+ *
+ * The groups `@agent`, `@here`, and `@all` address the agent. `@humans`
+ * and `@humans_here` do not. Individual user mentions are also not matched
+ * here — agent addressing is group-based.
+ *
+ * @param mentions - Parsed mentions from {@link parseMentions}.
+ * @docLink packages/session/api-reference#mention-resolver
+ */
+export declare function isAgentAddressed(mentions: Mention[]): boolean;
+//# sourceMappingURL=mentions.d.ts.map

package/dist/session/src/mentions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mentions.d.ts","sourceRoot":"","sources":["../../../session/src/mentions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAEtE;;;GAGG;AACH,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;AAMtC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnE;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAAC;IAC5C,8FAA8F;IAC9F,gBAAgB,IAAI,MAAM,EAAE,CAAC;CAC9B;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,EAAE,CAkChF;AAMD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAMxE;AASD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAE7D"}

package/dist/session/src/types.d.ts

@@ -0,0 +1,109 @@
+import type { AgentEvent, Message, MessageV2 } from "@skaile/workspaces/types";
+export type { Message };
+/**
+ * Metadata associated with a subscriber for recipients filtering.
+ *
+ * @docLink packages/session/api-reference#interfaces
+ */
+export type SubscriberInfo = {
+    userId?: string;
+    roles?: string[];
+};
+/**
+ * Persistent message storage — append-only log with seq-based pagination.
+ *
+ * Generic over `TMessage` so platforms with typed `MessageMeta` extensions
+ * can use a typed `MessageV2<TMetaExtensions>` consistently across their
+ * `append`/`getMessages` surface. Defaults to the concrete {@link Message}
+ * shape (`MessageV2<{}>` plus v1 back-compat fields).
+ *
+ * Each session has exactly one store. Implementations range from JSONL files
+ * (forge apps) to Prisma-backed PostgreSQL (platform) and in-memory arrays
+ * (tests). The store is never queried for transient messages — those are
+ * forwarded and broadcast but never appended.
+ *
+ * @example
+ * ```ts
+ * const store: MessageStore = new PrismaMessageStore(prisma)
+ * await store.append(message)
+ * const history = await store.getMessages(sessionId, { limit: 50 })
+ * ```
+ *
+ * @docLink packages/session/api-reference#interfaces
+ */
+export interface MessageStore<TMessage extends MessageV2<object> = Message> {
+    /** Persist a message to the session's append-only log. */
+    append(message: TMessage): Promise<void>;
+    /**
+     * Retrieve messages for a session, ordered by seq ascending.
+     *
+     * @param sessionId - The session to query.
+     * @param opts - Optional pagination parameters.
+     * @param opts.before - Return messages with seq < before (for backward pagination).
+     * @param opts.limit - Maximum number of messages to return.
+     */
+    getMessages(sessionId: string, opts?: {
+        before?: number;
+        limit?: number;
+    }): Promise<TMessage[]>;
+    /**
+     * Return the highest seq number for a session, or 0 if no messages exist.
+     *
+     * Used by `SessionDispatcher.init()` to restore the monotonic counter
+     * after a reconnect without re-reading the full message history.
+     *
+     * @param sessionId - The session to query.
+     */
+    getLatestSeq(sessionId: string): Promise<number>;
+    /**
+     * Retrieve messages for restore: returns the last snapshot (if any) plus
+     * all messages after it. Falls back to getMessages() if no snapshot exists.
+     */
+    getMessagesFromSnapshot?(sessionId: string): Promise<TMessage[]>;
+}
+/**
+ * Pushes real-time events to connected frontend subscribers.
+ *
+ * One subscriber ID per active WebSocket or SSE connection. Implementations
+ * include `EventEmitterSubscriberTransport` (platform, backed by Node.js
+ * EventEmitter + tRPC SSE iterator) and in-process callbacks (forge/tests).
+ *
+ * @example
+ * ```ts
+ * const transport: SubscriberTransport = new EventEmitterSubscriberTransport()
+ * transport.send('conn-abc', event)   // push to one subscriber
+ * transport.remove('conn-abc')        // clean up on disconnect
+ * ```
+ *
+ * @docLink packages/session/api-reference#interfaces
+ */
+export interface SubscriberTransport {
+    /**
+     * Send an event to a specific subscriber.
+     *
+     * **Visibility-filtering contract (since @skaile/workspaces/types 3.2):**
+     * implementations handling sessions where `UserMessageEvent` carries
+     * `visibilityMode !== "Public"` MUST gate delivery on the subscriber's
+     * identity (`SubscriberInfo.userId` and/or `roles`) against the
+     * event's `privateRecipientIds`. A naive forwarder that delivers
+     * every event to every subscriber will broadcast Private messages to
+     * non-recipients. The reference platform implementation gates this
+     * in its tRPC SSE iterator before yielding each event upstream.
+     * Non-platform consumers (e.g. forge apps) that don't run multi-user
+     * sessions can ignore this clause — they will only ever see
+     * `visibilityMode: "Public"` (or undefined) on the wire.
+     *
+     * @param subscriberId - Opaque identifier assigned at subscribe time.
+     * @param event - The agent event to deliver.
+     */
+    send(subscriberId: string, event: AgentEvent): void;
+    /**
+     * Remove a subscriber and release any associated resources.
+     *
+     * Safe to call multiple times for the same ID.
+     *
+     * @param subscriberId - The subscriber to remove.
+     */
+    remove(subscriberId: string): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/session/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../session/src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE/E,YAAY,EAAE,OAAO,EAAE,CAAC;AAExB;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,SAAS,SAAS,CAAC,MAAM,CAAC,GAAG,OAAO;IACxE,0DAA0D;IAC1D,MAAM,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;;;;;;OAOG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEhG;;;;;;;OAOG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjD;;;OAGG;IACH,uBAAuB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CAClE;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAEpD;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC"}

package/dist/sessions-2IUX4P3P.js

@@ -0,0 +1,5 @@
+export { readAllSessions, sessionGet, sessionList } from './chunk-HK5FRWG6.js';
+import './chunk-X5YPJV4N.js';
+import './chunk-NSBPE2FW.js';
+//# sourceMappingURL=sessions-2IUX4P3P.js.map
+//# sourceMappingURL=sessions-2IUX4P3P.js.map

package/dist/sessions-2IUX4P3P.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sessions-2IUX4P3P.js"}