@vascend/talos 0.1.0

package/dist/extensions/types.d.ts

@@ -0,0 +1,219 @@
+import type { Message, Tool, ToolHandlerOutput, ToolResultPart } from "../core/types.js";
+import type { JsonSchema } from "../mcp/protocol.js";
+import type { SessionNode } from "../core/session.js";
+export interface SlashCommand {
+    readonly name: string;
+    readonly description: string;
+    run(args: string, api: ExtensionApi): Promise<string | null>;
+}
+export interface ShortcutDef {
+    readonly key: string;
+    readonly description: string;
+    run(ctx: ExtensionContext): void | Promise<void>;
+}
+export interface FlagDef {
+    readonly name: string;
+    readonly description: string;
+    readonly hasValue?: boolean;
+    run(value: string | undefined, ctx: ExtensionContext): void | Promise<void>;
+}
+export type MessageRenderer = (data: unknown, columns: number) => readonly string[];
+export type RunMode = "tui" | "print" | "rpc" | "json" | "sdk";
+export interface ExtensionUi {
+    confirm(title: string, message: string): Promise<boolean>;
+    select<T>(title: string, items: readonly {
+        label: string;
+        value: T;
+    }[]): Promise<T | null>;
+    input(title: string, opts?: {
+        placeholder?: string;
+    }): Promise<string | null>;
+    notify(message: string, type?: "info" | "warn" | "error"): void;
+    setStatus(id: string, text: string): void;
+    setWidget(id: string, lines: readonly string[]): void;
+}
+export interface SessionView {
+    entries(): readonly SessionNode[];
+    getBranch(): readonly SessionNode[];
+    getLeafId(): string | null;
+}
+export interface PiToolDefinition {
+    readonly name: string;
+    readonly label?: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly parameters: JsonSchema;
+    readonly outputSchema?: JsonSchema;
+    execute(toolCallId: string, params: Record<string, unknown>, signal: AbortSignal, onUpdate: (partial: unknown) => void, ctx: ExtensionContext): Promise<string | ToolHandlerOutput | {
+        readonly content?: ToolHandlerOutput["content"];
+        readonly details?: unknown;
+        readonly isError?: boolean;
+    }>;
+}
+export interface PiCommandOptions {
+    readonly description: string;
+    handler(args: string, ctx: ExtensionContext): unknown | Promise<unknown>;
+}
+export interface PiShortcutOptions {
+    readonly description: string;
+    handler(ctx: ExtensionContext): void | Promise<void>;
+}
+export interface PiFlagOptions {
+    readonly description: string;
+    readonly type?: "boolean" | "string";
+    readonly default?: boolean | string;
+}
+export interface PiToolInfo {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: JsonSchema;
+    readonly sourceInfo: {
+        readonly path: string;
+        readonly source: "builtin" | "extension";
+        readonly scope: "temporary";
+        readonly origin: "top-level";
+    };
+}
+export interface PiExecOptions {
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly signal?: AbortSignal;
+    readonly timeout?: number;
+}
+export interface PiExecResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+    readonly killed: boolean;
+}
+export interface PiCustomMessage {
+    readonly customType?: string;
+    readonly content: string | readonly {
+        readonly type: string;
+        readonly text?: string;
+    }[];
+    readonly display?: boolean;
+    readonly details?: unknown;
+}
+export interface ExtensionSharedEvents {
+    on(name: string, handler: (data: unknown) => void): void;
+    off(name: string, handler: (data: unknown) => void): void;
+    emit(name: string, data: unknown): void;
+}
+export interface ExtensionContext {
+    readonly cwd: string;
+    readonly mode: RunMode;
+    readonly hasUI: boolean;
+    isProjectTrusted(): boolean;
+    getContextUsage(): {
+        readonly tokens: number;
+        readonly window: number;
+    };
+    getSystemPrompt(): string;
+    getSystemPromptOptions(): {
+        readonly base: string;
+        readonly appended: readonly string[];
+    };
+    readonly ui: ExtensionUi;
+    readonly sessionManager: SessionView;
+}
+export interface ExtensionEvents {
+    readonly session_start: {
+        readonly reason: "startup" | "new" | "resume" | "fork";
+    };
+    readonly session_shutdown: Record<string, never>;
+    readonly before_agent_start: {
+        readonly input: string;
+    };
+    readonly agent_start: {
+        readonly input: string;
+    };
+    readonly agent_end: Record<string, never>;
+    readonly turn_start: {
+        readonly turn: number;
+    };
+    readonly turn_end: {
+        readonly stopReason: string;
+    };
+    readonly tool_call: {
+        readonly toolName: string;
+        readonly input: Record<string, unknown>;
+    };
+    readonly tool_result: {
+        readonly toolName: string;
+        readonly result: ToolResultPart;
+    };
+    readonly context: {
+        readonly messages: readonly Message[];
+    };
+    readonly project_trust: {
+        readonly trusted: boolean;
+        readonly cwd: string;
+        readonly resources: readonly string[];
+        readonly source: "default" | "stored" | "prompt";
+    };
+}
+export type EventName = keyof ExtensionEvents;
+export interface EventOutcome {
+    readonly block?: boolean;
+    readonly reason?: string;
+    readonly result?: ToolResultPart;
+    readonly messages?: readonly Message[];
+    readonly message?: {
+        readonly content: string;
+        readonly display?: boolean;
+    };
+    readonly systemAppend?: string;
+}
+export type EventHandler<E extends EventName> = (event: ExtensionEvents[E], ctx: ExtensionContext) => EventOutcome | void | Promise<EventOutcome | void>;
+export interface CustomProviderConfig {
+    readonly baseUrl?: string;
+    readonly apiKey?: string;
+    readonly models?: readonly string[];
+    readonly label?: string;
+}
+export interface ExtensionApi {
+    readonly cwd: string;
+    registerTool(tool: Tool | PiToolDefinition): void;
+    registerCommand(cmd: SlashCommand): void;
+    registerCommand(name: string, options: PiCommandOptions): void;
+    registerShortcut(shortcut: ShortcutDef): void;
+    registerShortcut(key: string, options: PiShortcutOptions): void;
+    registerFlag(flag: FlagDef): void;
+    registerFlag(name: string, options: PiFlagOptions): void;
+    getFlag(name: string): boolean | string | undefined;
+    getAllTools(): readonly PiToolInfo[];
+    getActiveTools(): readonly string[];
+    setActiveTools(names: readonly string[]): void;
+    exec(command: string, args: readonly string[], options?: PiExecOptions): Promise<PiExecResult>;
+    readonly events: ExtensionSharedEvents;
+    registerProvider(name: string, config: CustomProviderConfig): void;
+    unregisterProvider(name: string): void;
+    registerMessageRenderer(customType: string, renderer: MessageRenderer): void;
+    onSystemPrompt(fn: (base: string) => string): void;
+    on<E extends EventName>(event: E, handler: EventHandler<E>): void;
+    sendMessage(content: string | PiCustomMessage, opts?: {
+        display?: boolean;
+        triggerTurn?: boolean;
+        deliverAs?: string;
+    }): void;
+    sendUserMessage(content: string | readonly {
+        readonly type: string;
+        readonly text?: string;
+    }[], opts?: {
+        deliverAs?: string;
+    }): void;
+    appendEntry(customType: string, data?: unknown): void;
+    setSessionName(name: string): void;
+    setLabel(entryId: string, label: string): void;
+    log(msg: string): void;
+    reloadExtensions(): Promise<{
+        before: string[];
+        after: string[];
+        added: string[];
+        removed: string[];
+    }>;
+    getSettings(): Record<string, unknown>;
+    setSetting(key: string, value: unknown): void;
+}
+export type Extension = (api: ExtensionApi) => void | Promise<void>;

package/dist/extensions/types.js

@@ -0,0 +1 @@
+export {};

package/dist/horizon/async-queue.d.ts

@@ -0,0 +1,9 @@
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    private readonly buffered;
+    private readonly waiting;
+    private closed;
+    private iteratorClaimed;
+    push(value: T): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/horizon/async-queue.js

@@ -0,0 +1,46 @@
+// Coda push -> AsyncIterable, intenzionalmente minimale e senza dipendenze UI.
+// Un HorizonTurn ha un solo consumer: l'host drena gli eventi nell'ordine in
+// cui Talos li emette, inclusi i delta testuali.
+export class AsyncQueue {
+    buffered = [];
+    waiting = [];
+    closed = false;
+    iteratorClaimed = false;
+    push(value) {
+        if (this.closed)
+            return;
+        const resolve = this.waiting.shift();
+        if (resolve)
+            resolve({ value, done: false });
+        else
+            this.buffered.push(value);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const resolve of this.waiting.splice(0)) {
+            resolve({ value: undefined, done: true });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        if (this.iteratorClaimed) {
+            throw new Error("lo stream di un HorizonTurn puo' essere consumato una sola volta");
+        }
+        this.iteratorClaimed = true;
+        return {
+            next: () => {
+                const value = this.buffered.shift();
+                if (value !== undefined)
+                    return Promise.resolve({ value, done: false });
+                if (this.closed)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.waiting.push(resolve));
+            },
+            return: () => {
+                this.close();
+                return Promise.resolve({ value: undefined, done: true });
+            },
+        };
+    }
+}

package/dist/horizon/engine.d.ts

@@ -0,0 +1,85 @@
+import type { SpawnAgentSpec } from "../core/types.js";
+import { type VibeModeSelection } from "../core/vibe-modes.js";
+import type { HorizonCapabilityDescriptor, HorizonContextStatus, HorizonEngineOptions, HorizonEngineState, HorizonModelCatalog, HorizonModelInspectionOptions, HorizonRuntime, HorizonSessionListItem, HorizonSessionSnapshot, HorizonTurn, HorizonTurnInput, HorizonTurnOptions, HorizonVibeStatus } from "./types.js";
+export declare const HORIZON_CAPABILITIES: HorizonCapabilityDescriptor;
+export declare class HorizonStateError extends Error {
+    readonly code = "HORIZON_INVALID_STATE";
+    constructor(message: string);
+}
+export declare class HorizonSessionNotFoundError extends Error {
+    readonly sessionId: string;
+    readonly code = "HORIZON_SESSION_NOT_FOUND";
+    constructor(sessionId: string);
+}
+export declare class HorizonContextUnavailableError extends Error {
+    readonly code = "HORIZON_CONTEXT_UNAVAILABLE";
+    constructor();
+}
+/** Applica il pool autorizzato senza permettere override arbitrari dal modello. */
+export declare function routeWorkerModels(castles: readonly SpawnAgentSpec[], configuredPool: readonly string[] | undefined): readonly SpawnAgentSpec[];
+/**
+ * Facade headless ufficiale di Talos per Vascend Terminal/Horizon.
+ *
+ * Invarianti del contratto:
+ * - nessuna dipendenza Electron o TUI;
+ * - un solo turno in volo per engine/sessione;
+ * - eventi ordinati su AsyncIterable, con completamento sempre osservabile;
+ * - cambio sessione, vibe e context mutation vietati durante un turno;
+ * - permission gate deny-by-default, fornito dal processo host.
+ */
+export declare class HorizonEngine {
+    private readonly harness;
+    private readonly options;
+    private readonly runtime;
+    private stateValue;
+    private active;
+    private turnSequence;
+    private constructor();
+    static create(options?: HorizonEngineOptions, runtime?: HorizonRuntime): Promise<HorizonEngine>;
+    /**
+     * Ispeziona i modelli realmente instradabili senza avviare Talos. Usa le
+     * stesse credenziali persistite e lo stesso ProviderRegistry del bootstrap,
+     * ma non crea Harness, sessioni, tool, estensioni o stato nel workspace.
+     */
+    static inspectModels(options?: HorizonModelInspectionOptions): HorizonModelCatalog;
+    get state(): HorizonEngineState;
+    get capabilities(): HorizonCapabilityDescriptor;
+    get session(): HorizonSessionSnapshot;
+    listSessions(): readonly HorizonSessionListItem[];
+    newSession(options?: {
+        readonly name?: string;
+    }): HorizonSessionSnapshot;
+    resumeSession(id: string): HorizonSessionSnapshot;
+    renameSession(name: string): HorizonSessionSnapshot;
+    setModel(model: string): HorizonSessionSnapshot;
+    /**
+     * Catalogo autoritativo per il selector dell'host. Non usa il catalogo
+     * statico: legge ogni volta il ProviderRegistry corrente, quindi non espone
+     * provider privi di credenziali e riflette subito setModel/reloadProviders.
+     */
+    modelCatalog(): HorizonModelCatalog;
+    /** Rilegge le credenziali Talos e restituisce nello stesso giro il catalogo aggiornato. */
+    reloadProviders(): HorizonModelCatalog;
+    vibe(): HorizonVibeStatus;
+    setVibeMode(value: VibeModeSelection): HorizonVibeStatus;
+    contextStatus(): HorizonContextStatus;
+    pinContext(values: string | readonly string[]): HorizonContextStatus;
+    unpinContext(values: string | readonly string[]): HorizonContextStatus;
+    resetContext(options?: {
+        readonly preservePins?: boolean;
+    }): HorizonContextStatus;
+    startTurn(input: HorizonTurnInput, options?: HorizonTurnOptions): HorizonTurn;
+    /**
+     * Consegna un messaggio al turno attualmente in corso, senza doverne
+     * conservare il riferimento. Null se in questo momento non c'e' nulla in
+     * volo: sta all'host aprire allora un turno normale.
+     */
+    sendToActiveTurn(input: HorizonTurnInput, id?: string): string | null;
+    abortTurn(id?: string): boolean;
+    close(): Promise<void>;
+    private sessionSnapshot;
+    private currentFrame;
+    private contextSnapshot;
+    private assertOpen;
+    private assertMutable;
+}