@skrr-ai/cli 0.1.8

package/dist/lib/agent-config.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeAgentConfigFlags = mergeAgentConfigFlags;
+const prompt_1 = require("./prompt");
+/** Apply the structured agent fields exposed by the web config editor. */
+function mergeAgentConfigFlags(body, flags) {
+    const json = {
+        tools: 'tools',
+        'model-parameters': 'model_parameters',
+        'agent-ids': 'agent_ids',
+        'network-agent-ids': 'network_agent_ids',
+        'agent-actions': 'agentActions',
+        skills: 'skills',
+        'tool-policy': 'toolPolicy',
+        artifacts: 'artifacts',
+        'support-contact': 'support_contact',
+        'install-first-contact': 'installFirstContact',
+    };
+    const parsed = {};
+    for (const [flag, field] of Object.entries(json)) {
+        const value = flags[flag];
+        if (value !== undefined)
+            parsed[field] = JSON.parse(String(value));
+    }
+    const direct = {
+        'network-mode': 'network_mode',
+        'character-3d-id': 'character3DId',
+        'scene-background': 'sceneBackground',
+        'tone-mode': 'toneMode',
+        'tone-id': 'toneId',
+        'tone-notes': 'toneNotes',
+        'working-directory': 'workingDirectory',
+        'default-permission-mode': 'defaultPermissionMode',
+    };
+    for (const [flag, field] of Object.entries(direct)) {
+        if (flags[flag] !== undefined)
+            parsed[field] = flags[flag];
+    }
+    const booleans = {
+        'network-include-public': 'network_include_public',
+        'end-after-tools': 'end_after_tools',
+        'hide-sequential-outputs': 'hide_sequential_outputs',
+        'is-collaborative': 'isCollaborative',
+    };
+    for (const [flag, field] of Object.entries(booleans)) {
+        if (flags[flag] !== undefined)
+            parsed[field] = flags[flag];
+    }
+    if (flags['recursion-limit'] !== undefined)
+        parsed.recursion_limit = flags['recursion-limit'];
+    return (0, prompt_1.mergeDefined)(body, parsed);
+}

package/dist/lib/agent-resolver.d.ts

@@ -0,0 +1,50 @@
+export type AgentResolutionCode = 'AGENT_CONTEXT_CONFLICT' | 'AGENT_CONTEXT_MISSING' | 'AGENT_CONTEXT_AMBIGUOUS' | 'AGENT_RESOLUTION_FAILED';
+export type ResolvedAgentIdentity = {
+    id: string;
+    source: 'explicit' | 'OVERSKY_SESSION_AGENT_ID' | 'OVERSKY_AGENT_ID' | 'single_visible_agent';
+    boundToSession: boolean;
+};
+export declare class AgentResolutionError extends Error {
+    code: AgentResolutionCode;
+    suggestion: string;
+    details?: Record<string, unknown>;
+    constructor({ code, message, suggestion, details, }: {
+        code: AgentResolutionCode;
+        message: string;
+        suggestion: string;
+        details?: Record<string, unknown>;
+    });
+}
+/**
+ * Resolve the agent ID to use for a composio command.
+ *
+ * Resolution order:
+ *   1. Explicit agent ID from a command argument or `--agent <id>` flag.
+ *   2. `OVERSKY_SESSION_AGENT_ID` environment variable (set by daemon-scoped local runtimes).
+ *   3. `OVERSKY_AGENT_ID` environment variable (legacy/manual local runtime binding).
+ *   4. User's primary agent, if exactly one agent exists.
+ *
+ * Throws a clear error if the agent is ambiguous or none exists.
+ */
+export declare function resolveAgentIdentity(explicitAgentId?: string): Promise<ResolvedAgentIdentity>;
+/**
+ * Resolve identity for a session-credential command without cloud discovery.
+ *
+ * A session token is meaningful only together with the daemon's canonical
+ * `OVERSKY_SESSION_AGENT_ID` binding. Explicit positional/flag/JSON input may
+ * confirm that binding, but can neither replace nor override it. This keeps a
+ * malformed autonomous environment from consulting `listAgents()` with any
+ * ambient credential.
+ */
+export declare function resolveSessionAgentIdentity(explicitAgentId?: string, env?: Record<string, string | undefined>): ResolvedAgentIdentity;
+export declare function resolveAgentId(flagValue?: string): Promise<string>;
+export declare function mergeExplicitAgentInputs(inputs: Array<{
+    label: string;
+    value?: string | null;
+}>): string | undefined;
+export declare function agentResolutionFailure(err: unknown): {
+    code: AgentResolutionCode;
+    message: string;
+    suggestion: string;
+    details?: Record<string, unknown>;
+};

package/dist/lib/agent-resolver.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentResolutionError = void 0;
+exports.resolveAgentIdentity = resolveAgentIdentity;
+exports.resolveSessionAgentIdentity = resolveSessionAgentIdentity;
+exports.resolveAgentId = resolveAgentId;
+exports.mergeExplicitAgentInputs = mergeExplicitAgentInputs;
+exports.agentResolutionFailure = agentResolutionFailure;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const runtime_context_1 = require("./runtime-context");
+class AgentResolutionError extends Error {
+    code;
+    suggestion;
+    details;
+    constructor({ code, message, suggestion, details, }) {
+        super(message);
+        this.name = 'AgentResolutionError';
+        this.code = code;
+        this.suggestion = suggestion;
+        this.details = details;
+    }
+}
+exports.AgentResolutionError = AgentResolutionError;
+/**
+ * Resolve the agent ID to use for a composio command.
+ *
+ * Resolution order:
+ *   1. Explicit agent ID from a command argument or `--agent <id>` flag.
+ *   2. `OVERSKY_SESSION_AGENT_ID` environment variable (set by daemon-scoped local runtimes).
+ *   3. `OVERSKY_AGENT_ID` environment variable (legacy/manual local runtime binding).
+ *   4. User's primary agent, if exactly one agent exists.
+ *
+ * Throws a clear error if the agent is ambiguous or none exists.
+ */
+async function resolveAgentIdentity(explicitAgentId) {
+    const runtime = (0, runtime_context_1.readRuntimeContext)();
+    if (runtime.agent?.source === 'OVERSKY_SESSION_AGENT_ID') {
+        if (explicitAgentId && explicitAgentId !== runtime.agent.id) {
+            throw new AgentResolutionError({
+                code: 'AGENT_CONTEXT_CONFLICT',
+                message: 'This local runtime is bound to OVERSKY_SESSION_AGENT_ID. Do not override it with another agent ID.',
+                suggestion: 'Use the bound session agent, or start a new daemon session for a different agent.',
+                details: {
+                    explicitAgentId,
+                    sessionAgentId: runtime.agent.id,
+                    source: runtime.agent.source,
+                },
+            });
+        }
+        return {
+            id: runtime.agent.id,
+            source: runtime.agent.source,
+            boundToSession: true,
+        };
+    }
+    if (explicitAgentId) {
+        return { id: explicitAgentId, source: 'explicit', boundToSession: false };
+    }
+    if (runtime.agent?.source === 'OVERSKY_AGENT_ID') {
+        return {
+            id: runtime.agent.id,
+            source: runtime.agent.source,
+            boundToSession: false,
+        };
+    }
+    // Auto-selection is intentionally stricter than browsing. A public/view-only
+    // Agent can appear in the roster but the authored-DM delivery primitive will
+    // reject it. EDIT is the safe server-backed approximation for an owned or
+    // collaborative Agent; callers with view-only collaboration can still pass
+    // an explicit --agent and receive the authoritative route decision.
+    //
+    // WHO MAY ASK THIS QUESTION. Every caller below is a command whose SUBJECT is
+    // an agent — "show this agent's DM", "send as this agent", "attach a harness
+    // to this agent". There, "which agent?" is the question the command exists to
+    // answer, so asking the operator to disambiguate is correct.
+    //
+    // Task creation used to call this too, to fill in a DEFAULT, and that was the
+    // defect: it turned "who am I" into a roster lookup that either failed the
+    // whole command (several agents ⇒ AGENT_CONTEXT_AMBIGUOUS, exit 2, no task
+    // recorded) or answered confidently and wrongly (exactly one ⇒ an agent with
+    // no connection to this session). Identity for a default now comes only from
+    // what the session proves — see `boundSessionAgentId` in `lib/tasks.ts`.
+    //
+    // The rule this leaves behind: ask when the agent is the OBJECT of the
+    // command; never ask to fill in a default.
+    const resp = await data_provider_1.dataService.listAgents({ limit: 2, requiredPermission: data_provider_1.PermissionBits.EDIT });
+    // listAgents returns AgentListResponse which has a data property
+    const items = (resp?.data ?? resp);
+    if (items.length === 0) {
+        throw new AgentResolutionError({
+            code: 'AGENT_CONTEXT_MISSING',
+            message: 'No current agent is bound and no message-eligible agents were found.',
+            suggestion: 'Run `skrr context --json` to inspect runtime identity, or pass `--agent <agent-id>`.',
+            details: { runtimeKind: runtime.kind },
+        });
+    }
+    if (items.length > 1) {
+        throw new AgentResolutionError({
+            code: 'AGENT_CONTEXT_AMBIGUOUS',
+            message: 'Multiple agents found. Specify an agent ID or set OVERSKY_SESSION_AGENT_ID/OVERSKY_AGENT_ID.',
+            suggestion: 'In daemon sessions prefer OVERSKY_SESSION_AGENT_ID. In scripts pass `--agent <agent-id>`.',
+            details: {
+                messageEligibleAgentCount: items.length,
+                runtimeKind: runtime.kind,
+            },
+        });
+    }
+    return { id: items[0].id, source: 'single_visible_agent', boundToSession: false };
+}
+/**
+ * Resolve identity for a session-credential command without cloud discovery.
+ *
+ * A session token is meaningful only together with the daemon's canonical
+ * `OVERSKY_SESSION_AGENT_ID` binding. Explicit positional/flag/JSON input may
+ * confirm that binding, but can neither replace nor override it. This keeps a
+ * malformed autonomous environment from consulting `listAgents()` with any
+ * ambient credential.
+ */
+function resolveSessionAgentIdentity(explicitAgentId, env = process.env) {
+    const runtime = (0, runtime_context_1.readRuntimeContext)(env);
+    if (runtime.agent?.source !== 'OVERSKY_SESSION_AGENT_ID') {
+        throw new AgentResolutionError({
+            code: 'AGENT_CONTEXT_MISSING',
+            message: 'This autonomous session has no canonical OVERSKY_SESSION_AGENT_ID; refusing agent discovery with ambient CLI authority.',
+            suggestion: 'Restart the daemon session so it supplies the bound session agent identity.',
+            details: { runtimeKind: runtime.kind, requiredSource: 'OVERSKY_SESSION_AGENT_ID' },
+        });
+    }
+    if (explicitAgentId && explicitAgentId !== runtime.agent.id) {
+        throw new AgentResolutionError({
+            code: 'AGENT_CONTEXT_CONFLICT',
+            message: 'This local runtime is bound to OVERSKY_SESSION_AGENT_ID. Do not override it with another agent ID.',
+            suggestion: 'Use the bound session agent, or start a new daemon session for a different agent.',
+            details: {
+                explicitAgentId,
+                sessionAgentId: runtime.agent.id,
+                source: runtime.agent.source,
+            },
+        });
+    }
+    return {
+        id: runtime.agent.id,
+        source: runtime.agent.source,
+        boundToSession: true,
+    };
+}
+async function resolveAgentId(flagValue) {
+    return (await resolveAgentIdentity(flagValue)).id;
+}
+function mergeExplicitAgentInputs(inputs) {
+    const present = inputs
+        .map((input) => ({
+        label: input.label,
+        value: typeof input.value === 'string' ? input.value.trim() : '',
+    }))
+        .filter((input) => input.value);
+    const first = present[0]?.value;
+    if (first && present.some((input) => input.value !== first)) {
+        throw new AgentResolutionError({
+            code: 'AGENT_CONTEXT_CONFLICT',
+            message: `Agent inputs conflict: ${present.map((input) => input.label).join(', ')}.`,
+            suggestion: 'Pass exactly one agent identity source, or rely on OVERSKY_SESSION_AGENT_ID.',
+            details: {
+                inputs: present,
+            },
+        });
+    }
+    return first;
+}
+function agentResolutionFailure(err) {
+    if (err instanceof AgentResolutionError) {
+        return {
+            code: err.code,
+            message: err.message,
+            suggestion: err.suggestion,
+            details: err.details,
+        };
+    }
+    return {
+        code: 'AGENT_RESOLUTION_FAILED',
+        message: err instanceof Error ? err.message : String(err),
+        suggestion: 'Run `skrr context --json` to inspect runtime identity.',
+    };
+}

package/dist/lib/agent-scope.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Client-side verification that a server actually honored an agent scope.
+ *
+ * `GET /api/convos?agentId=…` is a newer filter. Express silently ignores query
+ * params it does not read, so a CLI pointed at an older deployment gets a 200
+ * with plain recency — indistinguishable from a real answer, and wrong. Verified
+ * against oversky.dev before the server change shipped: `--agent <other-agent>`
+ * returned another agent's five newest conversations with no error.
+ *
+ * Callers check the returned rows and either fail loudly (`convos list`) or
+ * degrade to a client-side filter with a stated caveat (`agents activity`).
+ */
+export declare function agentIdOf(row: Record<string, unknown>): string | null;
+/** Rows the server returned that do NOT belong to the requested agent. */
+export declare function rowsOutsideAgentScope(rows: Array<Record<string, unknown>>, agentId: string): Array<Record<string, unknown>>;
+/**
+ * True when the response proves the server never applied the filter. A response
+ * with zero rows proves nothing either way, so it is NOT treated as unsupported —
+ * "this agent has no conversations" is a legitimate empty page.
+ */
+export declare function serverIgnoredAgentScope(rows: Array<Record<string, unknown>>, agentId: string): boolean;

package/dist/lib/agent-scope.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Client-side verification that a server actually honored an agent scope.
+ *
+ * `GET /api/convos?agentId=…` is a newer filter. Express silently ignores query
+ * params it does not read, so a CLI pointed at an older deployment gets a 200
+ * with plain recency — indistinguishable from a real answer, and wrong. Verified
+ * against oversky.dev before the server change shipped: `--agent <other-agent>`
+ * returned another agent's five newest conversations with no error.
+ *
+ * Callers check the returned rows and either fail loudly (`convos list`) or
+ * degrade to a client-side filter with a stated caveat (`agents activity`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentIdOf = agentIdOf;
+exports.rowsOutsideAgentScope = rowsOutsideAgentScope;
+exports.serverIgnoredAgentScope = serverIgnoredAgentScope;
+function agentIdOf(row) {
+    const value = row.agent_id ?? row.agentId;
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/** Rows the server returned that do NOT belong to the requested agent. */
+function rowsOutsideAgentScope(rows, agentId) {
+    return rows.filter((row) => agentIdOf(row) !== agentId);
+}
+/**
+ * True when the response proves the server never applied the filter. A response
+ * with zero rows proves nothing either way, so it is NOT treated as unsupported —
+ * "this agent has no conversations" is a legitimate empty page.
+ */
+function serverIgnoredAgentScope(rows, agentId) {
+    return rows.length > 0 && rowsOutsideAgentScope(rows, agentId).length > 0;
+}

package/dist/lib/agent-spaces.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `skrr agents spaces` — pure shaping over `GET /api/agents/:agent_id/spaces`.
+ *
+ * Roles are deliberately OPAQUE STRINGS here. The server owns the vocabulary
+ * (`AGENT_SPACE_ROLE_ORDER` in `api/server/routes/agents/v1.js`) and is the
+ * only thing that assigns one; it is output, never input, so there is no
+ * server-side validation for a CLI copy to drift from. Re-declaring the list
+ * to validate `--role` would mean a role added on the server is rejected by
+ * the CLI until someone remembers to update it — so `--role` filters on what
+ * the response actually carries and reports the roles it saw when nothing
+ * matches, which cannot go stale.
+ */
+export type AgentSpaceRow = {
+    ref: string;
+    title: string;
+    roles: string;
+    status: string;
+    id: string;
+};
+/** Roles the server attached to one space, normalized to a string array. */
+export declare function rolesOf(space: Record<string, unknown>): string[];
+/** Every distinct role present across the response, in first-seen order. */
+export declare function rolesPresent(spaces: Array<Record<string, unknown>>): string[];
+/**
+ * Keep spaces carrying ANY of `roles` — OR, not AND. `--role lead --role
+ * goal_dri` reads as "where this agent is in charge of something", which is
+ * the question that motivates repeating the flag; an AND would answer "leads
+ * the space AND happens to be DRI of a goal in it", which nobody asks.
+ *
+ * An empty/absent filter is not a filter — every space is kept.
+ */
+export declare function filterSpacesByRoles(spaces: Array<Record<string, unknown>>, roles: string[] | undefined): Array<Record<string, unknown>>;
+/** Table rows. `roles` is comma-joined in the server's precedence order. */
+export declare function toAgentSpaceRows(spaces: Array<Record<string, unknown>>): AgentSpaceRow[];

package/dist/lib/agent-spaces.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * `skrr agents spaces` — pure shaping over `GET /api/agents/:agent_id/spaces`.
+ *
+ * Roles are deliberately OPAQUE STRINGS here. The server owns the vocabulary
+ * (`AGENT_SPACE_ROLE_ORDER` in `api/server/routes/agents/v1.js`) and is the
+ * only thing that assigns one; it is output, never input, so there is no
+ * server-side validation for a CLI copy to drift from. Re-declaring the list
+ * to validate `--role` would mean a role added on the server is rejected by
+ * the CLI until someone remembers to update it — so `--role` filters on what
+ * the response actually carries and reports the roles it saw when nothing
+ * matches, which cannot go stale.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rolesOf = rolesOf;
+exports.rolesPresent = rolesPresent;
+exports.filterSpacesByRoles = filterSpacesByRoles;
+exports.toAgentSpaceRows = toAgentSpaceRows;
+/** Roles the server attached to one space, normalized to a string array. */
+function rolesOf(space) {
+    const roles = space._agentSpaceRoles;
+    if (!Array.isArray(roles))
+        return [];
+    return roles.filter((role) => typeof role === 'string' && role.length > 0);
+}
+/** Every distinct role present across the response, in first-seen order. */
+function rolesPresent(spaces) {
+    const seen = new Set();
+    for (const space of spaces) {
+        for (const role of rolesOf(space))
+            seen.add(role);
+    }
+    return [...seen];
+}
+/**
+ * Keep spaces carrying ANY of `roles` — OR, not AND. `--role lead --role
+ * goal_dri` reads as "where this agent is in charge of something", which is
+ * the question that motivates repeating the flag; an AND would answer "leads
+ * the space AND happens to be DRI of a goal in it", which nobody asks.
+ *
+ * An empty/absent filter is not a filter — every space is kept.
+ */
+function filterSpacesByRoles(spaces, roles) {
+    if (!roles || roles.length === 0)
+        return spaces;
+    const wanted = new Set(roles.map((role) => role.trim().toLowerCase()).filter(Boolean));
+    if (wanted.size === 0)
+        return spaces;
+    return spaces.filter((space) => rolesOf(space).some((role) => wanted.has(role.toLowerCase())));
+}
+/** Table rows. `roles` is comma-joined in the server's precedence order. */
+function toAgentSpaceRows(spaces) {
+    return spaces.map((space) => {
+        const roles = rolesOf(space);
+        return {
+            ref: String(space.identifier ?? '-'),
+            title: String(space.title ?? '-'),
+            // A space can only be in the response because a signal matched, so an
+            // empty array means the server did not label it — an older API build.
+            // Say so rather than printing a bare dash that reads as "no role".
+            roles: roles.length > 0 ? roles.join(', ') : '(unlabeled)',
+            status: String(space.status ?? '-'),
+            id: String(space.id ?? space._id ?? '-'),
+        };
+    });
+}

package/dist/lib/agent-thread.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Parse the public Agent Chat Thread coordinate without ever exposing a child
+ * Conversation ID as the CLI contract. Both the old positional form and the
+ * script-friendly flag form remain accepted:
+ *
+ *   skrr dm thread show <agent> <root>
+ *   skrr dm thread show <root> --agent <agent>
+ *   skrr dm thread show --agent <agent> --root <root>
+ */
+export declare function resolveAgentThreadTarget(input: {
+    positionalAgent?: string;
+    positionalRoot?: string;
+    flagAgent?: string;
+    flagRoot?: string;
+}): {
+    positionalAgent?: string;
+    rootMessageId: string;
+};
+export declare class AgentThreadTargetError extends Error {
+    constructor(message: string);
+}
+export declare function boundedThreadPageLimit(value: number | undefined): number;

package/dist/lib/agent-thread.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentThreadTargetError = void 0;
+exports.resolveAgentThreadTarget = resolveAgentThreadTarget;
+exports.boundedThreadPageLimit = boundedThreadPageLimit;
+/**
+ * Parse the public Agent Chat Thread coordinate without ever exposing a child
+ * Conversation ID as the CLI contract. Both the old positional form and the
+ * script-friendly flag form remain accepted:
+ *
+ *   skrr dm thread show <agent> <root>
+ *   skrr dm thread show <root> --agent <agent>
+ *   skrr dm thread show --agent <agent> --root <root>
+ */
+function resolveAgentThreadTarget(input) {
+    let positionalAgent = clean(input.positionalAgent);
+    let positionalRoot = clean(input.positionalRoot);
+    const flagAgent = clean(input.flagAgent);
+    const flagRoot = clean(input.flagRoot);
+    // With --agent supplied, one positional value is necessarily the root.
+    if (flagAgent && positionalAgent && !positionalRoot && !flagRoot) {
+        positionalRoot = positionalAgent;
+        positionalAgent = undefined;
+    }
+    if (positionalRoot && flagRoot && positionalRoot !== flagRoot) {
+        throw new AgentThreadTargetError('The positional root message ID and --root must match.');
+    }
+    const rootMessageId = positionalRoot || flagRoot;
+    if (!rootMessageId) {
+        throw new AgentThreadTargetError('A Thread root message ID is required. Pass <agent> <root>, <root> --agent <agent>, or --root <root>.');
+    }
+    return { positionalAgent, rootMessageId };
+}
+function clean(value) {
+    const trimmed = value?.trim();
+    return trimmed || undefined;
+}
+class AgentThreadTargetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentThreadTargetError';
+    }
+}
+exports.AgentThreadTargetError = AgentThreadTargetError;
+function boundedThreadPageLimit(value) {
+    const limit = value ?? 50;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+        throw new AgentThreadTargetError('--limit must be an integer between 1 and 200.');
+    }
+    return limit;
+}

package/dist/lib/agentic-stream.d.ts

@@ -0,0 +1,107 @@
+export type AgenticStreamEvent = {
+    type: string;
+    sessionId?: string;
+    [key: string]: unknown;
+};
+export type AgenticStreamResult = {
+    sessionId: string;
+    responseMessageId?: string;
+    text: string;
+    status: 'completed' | 'aborted' | 'failed';
+    lastEvent?: AgenticStreamEvent;
+};
+export type AgenticStreamOptions = {
+    baseURL: string;
+    token: string;
+    workspaceId?: string;
+    sessionId: string;
+    jsonl?: boolean;
+    approveTools?: boolean;
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    onEvent?: (event: AgenticStreamEvent) => void;
+    /**
+     * OSK-2936 — run the real turn but write nothing incrementally.
+     *
+     * This is what lets `--no-stream` be "the same agent turn, without the live
+     * output" instead of a different, non-executing code path. Events are still
+     * observed and text is still accumulated; only the stdout writes are
+     * suppressed, so the caller prints the final result itself.
+     */
+    quiet?: boolean;
+};
+/**
+ * Small Node-side adapter for the existing Agentic Socket.IO contract.
+ * It deliberately normalizes only lifecycle/text/tool events; the server's
+ * persisted envelope ring remains the source of truth for future replay UI.
+ */
+/**
+ * The assistant text inside a `session:output` frame's envelopes.
+ *
+ * Envelope shape: `{ ev: { t: 'text', text: '…' } }`. Frames whose `ev.t` is
+ * anything else (tool calls, status) are not the answer and are skipped.
+ */
+export declare function envelopesText(event: AgenticStreamEvent): string;
+/**
+ * Stable identity of one `session:output` envelope, for deduping re-delivered
+ * frames (OSK-4834).
+ *
+ * The server may deliver the same envelope on several channels (session room +
+ * user room + replay on join). Without a key the CLI appended each delivery,
+ * so the streamed text doubled ("P" → "PP") and `--jsonl` printed every event
+ * 2–4×. `id` alone can be shared across a message's envelopes, so `__seq` /
+ * `userSeq` are folded in to keep distinct envelopes distinct.
+ *
+ * Returns null when the envelope carries no identity fields — it then cannot be
+ * deduped and is treated as new, preserving prior behaviour for such frames.
+ */
+export declare function envelopeKey(envelope: unknown): string | null;
+/**
+ * The envelopes of a `session:output` frame not yet seen, recording each into
+ * `seen` as it passes. Envelopes without an identity (see `envelopeKey`) are
+ * always returned. A frame whose every envelope has already been seen yields an
+ * empty array — the caller drops it as a pure re-delivery (OSK-4834).
+ */
+export declare function unseenEnvelopes(event: AgenticStreamEvent, seen: Set<string>): unknown[];
+export declare class AgenticStreamClient {
+    private readonly options;
+    private socket;
+    private readline;
+    private cancelled;
+    private settled;
+    private closed;
+    private accumulated;
+    private readonly seenEnvelopes;
+    private responseMessageId;
+    private lastEvent;
+    private resolve;
+    private reject;
+    constructor(options: AgenticStreamOptions);
+    run(): Promise<AgenticStreamResult>;
+    cancel(reason?: string): void;
+    close(): void;
+    private installHandlers;
+    private handlePermission;
+    private handleQuestion;
+    private ask;
+    private emit;
+    private finish;
+    /**
+     * OSK-2944 — a transient connect failure must not end an ACCEPTED run.
+     *
+     * The socket is created with `reconnection: true`, but this used to reject on
+     * the FIRST `connect_error`, which threw straight out of `run()` and exited
+     * the CLI — defeating the reconnection it had just configured. The observed
+     * shape was `run.accepted` (the HTTP accept had already succeeded, so the run
+     * was queued server-side) immediately followed by `transport.error websocket
+     * error` and exit 1, while the daemon stayed live with zero missed
+     * heartbeats: a run that was very possibly executing, reported as a failure,
+     * with no way to tell the two apart.
+     *
+     * Now errors are surfaced as events and retried until a bounded deadline, so
+     * only a sustained inability to attach gives up — and the caller turns that
+     * into "accepted but detached", never "failed".
+     */
+    private waitForConnect;
+}
+export declare function toWebSocketOrigin(baseURL: string): string;