import type { Session } from "../shared/types.js";
import type { ApiContext } from "./api.js";
/**
 * Spawning a session, with nothing about HTTP in it.
 *
 * `POST /api/sessions` was the only way to start one, so a second caller — the
 * plugin host's `sessions.spawn` — would have had to reimplement employee
 * resolution, engine/model validation, the first message, the queue item and
 * the dispatch, and would have got one of them subtly wrong. The route keeps
 * what only a request can decide (who is asking, whose child this is, which
 * uploads came with it) and hands the rest here.
 */
/** Where a spawn came from, as the row records it. The default is the dashboard;
 *  a plugin passes its own so a session it started is attributable afterwards. */
export interface SpawnProvenance {
    source: string;
    sourceRef: string;
}
export interface SpawnSessionInput {
    prompt: string;
    /** Already coerced against the portal name by the caller, because whether a
     *  name is a pseudo-employee depends on config the caller has read. */
    employee?: string | null;
    engine?: unknown;
    model?: unknown;
    effortLevel?: unknown;
    parentSessionId?: string;
    promptExcerpt?: string;
    userId?: string;
    /** Uploaded file ids, as the web route receives them. */
    attachments?: unknown;
    /** Paste the prompt into the engine's PTY view when it has one. */
    interactive?: boolean;
    /** The prompt came from speech, so the engine hears a hidden context note the
     *  persisted and queued text never carries. */
    speech?: boolean;
    provenance?: SpawnProvenance;
}
/**
 * A refusal, or the session that now exists.
 *
 * `dispatched: false` is not a failure: the session was created and persisted
 * with its error on it, which is what the route has always answered 201 with.
 * Collapsing that into an error would change what an existing caller sees.
 */
export type SpawnSessionOutcome = {
    ok: false;
    error: string;
} | {
    ok: true;
    session: Session;
    dispatched: boolean;
};
export declare function spawnSession(context: ApiContext, input: SpawnSessionInput): Promise<SpawnSessionOutcome>;
//# sourceMappingURL=spawn-session.d.ts.map