@timurproko/a1 0.1.8-dev.50ebb19 → 0.1.8-dev.510

package/dist/composition/settings-route-host.js

@@ -0,0 +1,141 @@
+import { CHANGELOG_APP_ID, CHANGELOG_ROUTE, CHANGELOG_TITLE, HOTKEYS_APP_ID, HOTKEYS_ROUTE, HOTKEYS_TITLE, } from "../features/owned-ui/reference-routes.js";
+import { SETTINGS_APP_ID, SETTINGS_ROUTE } from "../features/owned-ui/settings-route.js";
+import { piTheme } from "../integrations/pi/components/upstream/theme/theme.js";
+import { faint } from "../ui/components/text.js";
+/**
+ * Declares the A1-owned settings route, and the changelog and hotkeys reference
+ * routes when their documents are supplied, without evaluating their presentation
+ * graphs during startup. Opening a route retains input while the optional module loads.
+ */
+export function createOwnedRouteHost(settings, references) {
+    const routes = new Set([SETTINGS_ROUTE, ...(references === undefined ? [] : [CHANGELOG_ROUTE, HOTKEYS_ROUTE])]);
+    return {
+        claims: route => routes.has(route),
+        open: (route, input) => {
+            if (!routes.has(route))
+                return null;
+            if (route === SETTINGS_ROUTE) {
+                return deferredSurface(SETTINGS_APP_ID, "settings", () => loadSettingsSurface(settings));
+            }
+            const changelog = route === CHANGELOG_ROUTE;
+            const id = changelog ? CHANGELOG_APP_ID : HOTKEYS_APP_ID;
+            const title = changelog ? CHANGELOG_TITLE : HOTKEYS_TITLE;
+            const document = changelog ? references.changelog(input) : references.hotkeys();
+            return deferredSurface(id, title, () => loadReferenceSurface(settings, id, route, title, document));
+        },
+    };
+}
+function deferredSurface(id, label, load) {
+    let delegate = null;
+    let closed = false;
+    let failure = null;
+    let onRender = () => undefined;
+    let onExit = () => undefined;
+    const pending = [];
+    void load().then(surface => {
+        if (closed) {
+            surface.close();
+            return;
+        }
+        delegate = surface;
+        surface.onRenderRequested(() => onRender());
+        surface.onExitRequested(() => onExit());
+        for (const action of pending.splice(0))
+            action(surface);
+        onRender();
+    }).catch(error => {
+        failure = `Could not load ${label}: ${error instanceof Error ? error.message : String(error)}`;
+        onRender();
+    });
+    const defer = (action) => {
+        if (delegate !== null)
+            action(delegate);
+        else if (!closed && pending.length < 32)
+            pending.push(action);
+    };
+    return {
+        id,
+        render: (width, height) => delegate?.render(width, height)
+            ?? Array.from({ length: Math.max(0, height) }, (_, row) => row === 0 && failure !== null ? failure.slice(0, Math.max(0, width)) : ""),
+        handleInput: data => { defer(surface => surface.handleInput(data)); return true; },
+        handleMouse: event => { defer(surface => surface.handleMouse(event)); return true; },
+        isClosed: () => closed || delegate?.isClosed() === true,
+        close: () => { closed = true; pending.length = 0; delegate?.close(); },
+        onRenderRequested: listener => { onRender = listener; },
+        onExitRequested: listener => { onExit = listener; },
+    };
+}
+async function loadSettingsSurface(settings) {
+    const { SettingsApp } = await import("../features/owned-ui/settings-app.js");
+    return hostApp(SETTINGS_APP_ID, SETTINGS_ROUTE, () => new SettingsApp(settings));
+}
+async function loadReferenceSurface(settings, id, route, title, document) {
+    // Rationale: the app module and the document load together, so a document that fails
+    // to render is reported by the placeholder rather than by a screen that never fills.
+    const [{ ReferenceScreenApp }, rows] = await Promise.all([import("../features/owned-ui/reference-screen-app.js"), document]);
+    return hostApp(id, route, () => new ReferenceScreenApp({
+        id,
+        title,
+        document: { rows },
+        scrollSettings: () => ({
+            scrollbarAppearance: settings.value("scrollbarAppearance"),
+            scrollbarStyle: settings.value("scrollbarStyle"),
+            scrollbarSpeed: settings.value("scrollbarSpeed"),
+        }),
+    }));
+}
+async function hostApp(id, route, create) {
+    const [{ UiAppHost }, { UiAppRegistry }] = await Promise.all([
+        import("../ui/apps/host.js"),
+        import("../ui/apps/registry.js"),
+    ]);
+    const registry = new UiAppRegistry();
+    registry.register({ id, route, create });
+    let size = { width: 80, height: 24 };
+    let frame = [];
+    let closed = false;
+    let onRender = () => undefined;
+    let onExit = () => undefined;
+    const host = new UiAppHost({
+        registry,
+        closeOnInterrupt: true,
+        theme: pinnedTheme(),
+        surface: {
+            size: () => size,
+            requestRender: () => onRender(),
+            exit: () => onExit(),
+            present: lines => {
+                if (lines === null)
+                    closed = true;
+                else
+                    frame = lines;
+            },
+        },
+    });
+    host.open(id);
+    return {
+        id,
+        render: (width, height) => {
+            size = { width, height };
+            host.render();
+            return frame.length === height ? frame : [...frame.slice(0, height), ...Array(Math.max(0, height - frame.length)).fill("")];
+        },
+        handleInput: data => host.handleInput(data).consumed,
+        handleMouse: event => host.handleMouse(event).consumed,
+        isClosed: () => closed || !host.isPresenting,
+        close: () => host.close(),
+        onRenderRequested: listener => { onRender = listener; },
+        onExitRequested: listener => { onExit = listener; },
+    };
+}
+/** Maps A1 UI tokens onto the pinned Pi theme so owned screens match the shell. */
+function pinnedTheme() {
+    return {
+        fg: (token, text) => piTheme().fg(token, text),
+        bold: (text) => piTheme().bold(text),
+        plain: (text) => text,
+        disabled: (text) => faint(piTheme().fg("dim", text)),
+        highlight: (text) => `\u001b[48;2;82;82;82m\u001b[97m${text}\u001b[39m\u001b[49m`,
+        panel: (text) => `\u001b[48;2;55;55;55m${text}\u001b[49m`,
+    };
+}

package/dist/contracts/agent-engine/capability-ports.d.ts

@@ -0,0 +1,95 @@
+import type { AgentJsonValue, AgentModelDescriptor, AgentSettingChangeOutcome, AgentResourceDescriptor, AgentSettingDescriptor } from "./domain.js";
+export interface AgentModelPort {
+    readonly capabilities: {
+        readonly selection: boolean;
+        readonly refresh: boolean;
+        readonly scopedCatalog: boolean;
+    };
+    listModels(scope?: string): Promise<readonly AgentModelDescriptor[]>;
+    currentModel(): Promise<AgentModelDescriptor | null>;
+    selectModel?(providerId: string, modelId: string): Promise<void>;
+    refreshModels?(): Promise<void>;
+}
+export interface AgentAuthenticationPort {
+    readonly capabilities: {
+        readonly login: boolean;
+        readonly logout: boolean;
+    };
+    status(providerId: string): Promise<"authenticated" | "unauthenticated" | "unavailable">;
+    login?(providerId: string, signal?: AbortSignal): Promise<void>;
+    logout?(providerId: string): Promise<void>;
+}
+export interface AgentSettingsPort {
+    readonly capabilities: {
+        readonly write: boolean;
+        readonly flush: boolean;
+    };
+    listSettings(): Promise<readonly AgentSettingDescriptor[]>;
+    readSetting(key: string): Promise<AgentJsonValue | undefined>;
+    writeSetting?(key: string, value: AgentJsonValue): Promise<AgentSettingChangeOutcome>;
+    flush?(): Promise<void>;
+}
+export interface AgentResourcesPort {
+    readonly capabilities: {
+        readonly reload: boolean;
+        readonly extensionBinding: boolean;
+    };
+    discoverResources(): Promise<readonly AgentResourceDescriptor[]>;
+    reload?(): Promise<void>;
+    bindExtensions?(sessionId: string): Promise<AgentExtensionBinding>;
+}
+export interface AgentExtensionBinding {
+    readonly sessionId: string;
+    dispose(): Promise<void>;
+}
+export interface AgentExtensionCommand {
+    readonly name: string;
+    readonly description: string;
+}
+export interface AgentSessionMetadata {
+    readonly sessionId: string;
+    readonly sessionName: string | null;
+    readonly sessionPath: string | null;
+    readonly cwd: string;
+}
+export interface AgentExtensionFailure {
+    readonly extensionPath: string | null;
+    readonly operation: string;
+    readonly message: string;
+    readonly recoverable: boolean;
+}
+export interface AgentExtensionPort {
+    readonly capabilities: {
+        readonly reload: boolean;
+        readonly binding: boolean;
+        readonly renderers: boolean;
+    };
+    discoverCommands(): Promise<readonly AgentExtensionCommand[]>;
+    sessionMetadata(): Promise<AgentSessionMetadata>;
+    bind?(sessionId: string): Promise<AgentExtensionBinding>;
+    reload?(): Promise<void>;
+    resolveMessageRenderer?(customType: string): unknown;
+    resolveToolRenderer?(toolName: string): unknown;
+    subscribeFailures(listener: (failure: AgentExtensionFailure) => void): () => void;
+}
+export interface AgentWorkflowDescriptor {
+    readonly id: string;
+    readonly label: string;
+    readonly requiredCommands: readonly string[];
+}
+export interface AgentWorkflowPort {
+    readonly capabilities: {
+        readonly execute: boolean;
+    };
+    listWorkflows(): Promise<readonly AgentWorkflowDescriptor[]>;
+    executeWorkflow?(workflowId: string, input: AgentJsonValue, signal?: AbortSignal): Promise<AgentJsonValue>;
+}
+export interface AgentServicePorts {
+    readonly models: AgentModelPort;
+    readonly authentication: AgentAuthenticationPort;
+    readonly settings: AgentSettingsPort;
+    readonly resources: AgentResourcesPort;
+    readonly extensions: AgentExtensionPort;
+    readonly workflows: AgentWorkflowPort;
+}
+export declare function assertAgentServicePorts(ports: AgentServicePorts): void;

package/dist/contracts/agent-engine/domain-validation.js

@@ -0,0 +1,107 @@
+const CONTENT = new Set(["text", "thinking", "image", "tool-call", "tool-result", "unknown"]);
+const CAPABILITIES = {
+    tools: new Set(["discovery", "invocation", "streaming-results"]),
+    usage: new Set(["tokens", "cache", "cost"]),
+    models: new Set(["discovery", "selection", "thinking-level"]),
+    settings: new Set(["read", "write"]),
+    resources: new Set(["commands", "prompts", "skills", "extensions", "themes"]),
+    uiContributions: new Set(["transcript", "tool", "editor", "status", "dialog", "overlay", "unknown"]),
+};
+const FAILURES = new Set(["configuration", "authentication", "authorization", "network", "rate-limit", "context-limit", "tool", "cancelled", "engine", "unknown"]);
+export function assertAgentDomainCapabilities(value) {
+    unique(value.messageContent, CONTENT, "message content capability");
+    for (const [key, allowed] of Object.entries(CAPABILITIES))
+        unique(value[key], allowed, `${key} capability`);
+}
+export function assertAgentMessage(message) {
+    id(message.id, "message id");
+    if (!["user", "assistant", "tool", "system"].includes(message.role) || !["streaming", "final"].includes(message.status))
+        throw new TypeError("message metadata is invalid");
+    if (!Array.isArray(message.content) || message.content.length === 0)
+        throw new TypeError("message content is empty");
+    for (const content of message.content)
+        assertAgentMessageContent(content);
+}
+export function assertAgentMessageContent(content) {
+    if (!CONTENT.has(content.kind))
+        throw new TypeError("message content kind is unknown and must use the unknown envelope");
+    if (content.kind === "text" || content.kind === "thinking")
+        text(content.text, "message text", true);
+    if (content.kind === "image") {
+        text(content.mediaType, "image media type");
+        text(content.data, "image data");
+    }
+    if (content.kind === "tool-call") {
+        id(content.invocationId, "tool invocation id");
+        id(content.toolName, "tool name");
+        json(content.input, "tool input");
+    }
+    if (content.kind === "tool-result") {
+        id(content.invocationId, "tool result invocation id");
+        json(content.output, "tool output");
+        if (typeof content.failed !== "boolean")
+            throw new TypeError("tool result failure flag is invalid");
+    }
+    if (content.kind === "unknown") {
+        text(content.sourceType, "unknown content source type");
+        json(content.payload, "unknown content payload");
+    }
+}
+export function assertAgentToolDescriptor(value) { id(value.name, "tool name"); text(value.description, "tool description", true); json(value.inputSchema, "tool input schema"); }
+export function assertAgentUsage(value) { for (const amount of [value.inputTokens, value.outputTokens, value.cacheReadTokens, value.cacheWriteTokens])
+    nonNegative(amount, "usage token count"); if (value.cost !== null && (!(typeof value.cost === "number") || !Number.isFinite(value.cost) || value.cost < 0))
+    throw new TypeError("usage cost is invalid"); }
+export function assertAgentModelDescriptor(value) { id(value.providerId, "model provider id"); id(value.modelId, "model id"); text(value.displayName, "model display name"); nonNegative(value.contextWindow, "model context window"); unique(value.thinkingLevels, undefined, "model thinking levels"); }
+export function assertAgentSettingDescriptor(value) {
+    id(value.key, "setting key");
+    if (!["boolean", "number", "string", "enum", "json"].includes(value.valueType)
+        || typeof value.writable !== "boolean"
+        || !["live", "next-session", "next-start", "current-exit"].includes(value.application)
+        || !["agent", "shell", "terminal", "startup", "shutdown", "installation"].includes(value.owner)
+        || typeof value.available !== "boolean"
+        || !(value.limitationReason === null || typeof value.limitationReason === "string")) {
+        throw new TypeError("setting descriptor is invalid");
+    }
+    json(value.storedValue, "stored setting value");
+    json(value.effectiveValue, "effective setting value");
+    if ((value.available && value.limitationReason !== null)
+        || (!value.available && (value.limitationReason === null || value.limitationReason.length === 0))) {
+        throw new TypeError("setting descriptor availability is contradictory");
+    }
+    if (value.writable && !value.available)
+        throw new TypeError("unavailable setting cannot be writable");
+    if (value.choices)
+        for (const choice of value.choices)
+            json(choice, "setting choice");
+}
+export function assertAgentResourceDescriptor(value) { id(value.id, "resource id"); if (!["command", "prompt", "skill", "extension", "other"].includes(value.kind))
+    throw new TypeError("resource kind is invalid"); text(value.label, "resource label"); json(value.metadata, "resource metadata"); }
+export function assertAgentThemeDescriptor(value) { id(value.id, "theme id"); text(value.label, "theme label"); if (!value.tokens || typeof value.tokens !== "object" || Object.values(value.tokens).some(token => typeof token !== "string"))
+    throw new TypeError("theme tokens are invalid"); }
+export function assertAgentUiContribution(value) { id(value.id, "UI contribution id"); if (!CAPABILITIES.uiContributions.has(value.slot) || !Number.isSafeInteger(value.version) || value.version < 1)
+    throw new TypeError("UI contribution metadata is invalid"); json(value.payload, "UI contribution payload"); }
+export function assertAgentFailure(value) { if (!FAILURES.has(value.category))
+    throw new TypeError("failure category is invalid"); id(value.code, "failure code"); text(value.message, "failure message"); if (typeof value.retryable !== "boolean")
+    throw new TypeError("failure retryability is invalid"); json(value.details, "failure details"); }
+function unique(values, allowed, label) { if (!Array.isArray(values))
+    throw new TypeError(`${label} must be an array`); const found = new Set(); for (const value of values) {
+    if ((allowed && !allowed.has(value)) || typeof value !== "string")
+        throw new TypeError(`${label} is invalid: ${String(value)}`);
+    if (found.has(value))
+        throw new TypeError(`${label} is duplicated: ${String(value)}`);
+    found.add(value);
+} }
+function id(value, label) { if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(value))
+    throw new TypeError(`${label} is invalid`); }
+function text(value, label, empty = false) { if (typeof value !== "string" || (!empty && value.length === 0) || Buffer.byteLength(value) > 256 * 1024)
+    throw new TypeError(`${label} is invalid`); }
+function nonNegative(value, label) { if (!Number.isSafeInteger(value) || value < 0)
+    throw new TypeError(`${label} is invalid`); }
+function json(value, label) { try {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined || Buffer.byteLength(encoded) > 256 * 1024)
+        throw new Error();
+}
+catch {
+    throw new TypeError(`${label} must be bounded JSON`);
+} }

package/dist/contracts/agent-engine/domain.d.ts

@@ -0,0 +1,138 @@
+export type AgentJsonValue = null | boolean | number | string | readonly AgentJsonValue[] | {
+    readonly [key: string]: AgentJsonValue;
+};
+export type AgentMessageContent = {
+    readonly kind: "text" | "thinking";
+    readonly text: string;
+} | {
+    readonly kind: "image";
+    readonly mediaType: string;
+    readonly data: string;
+} | {
+    readonly kind: "tool-call";
+    readonly invocationId: string;
+    readonly toolName: string;
+    readonly input: AgentJsonValue;
+} | {
+    readonly kind: "tool-result";
+    readonly invocationId: string;
+    readonly output: AgentJsonValue;
+    readonly failed: boolean;
+} | {
+    readonly kind: "unknown";
+    readonly sourceType: string;
+    readonly payload: AgentJsonValue;
+};
+export interface AgentMessage {
+    readonly id: string;
+    readonly role: "user" | "assistant" | "tool" | "system";
+    readonly status: "streaming" | "final";
+    readonly content: readonly AgentMessageContent[];
+}
+export interface AgentToolDescriptor {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: AgentJsonValue;
+}
+export interface AgentUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    readonly cost: number | null;
+}
+export interface AgentModelDescriptor {
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly displayName: string;
+    readonly contextWindow: number;
+    readonly thinkingLevels: readonly string[];
+}
+export type AgentSettingApplicationBoundary = "live" | "next-session" | "next-start" | "current-exit";
+export type AgentSettingOwner = "agent" | "shell" | "terminal" | "startup" | "shutdown" | "installation";
+export interface AgentSettingChangeOutcome {
+    readonly status: "applied" | "deferred" | "unavailable" | "failed";
+    readonly application: AgentSettingApplicationBoundary;
+    readonly storedValue: AgentJsonValue;
+    readonly effectiveValue: AgentJsonValue;
+    readonly failure: string | null;
+    readonly limitationReason: string | null;
+}
+export interface AgentSettingDescriptor {
+    readonly key: string;
+    readonly valueType: "boolean" | "number" | "string" | "enum" | "json";
+    /** A setting is writable only when its declared owner/effect is available. */
+    readonly writable: boolean;
+    readonly application: AgentSettingApplicationBoundary;
+    readonly owner: AgentSettingOwner;
+    readonly available: boolean;
+    readonly limitationReason: string | null;
+    readonly storedValue: AgentJsonValue;
+    readonly effectiveValue: AgentJsonValue;
+    readonly choices?: readonly AgentJsonValue[];
+    /** Label the engine shows for this setting, when it has one. */
+    readonly label?: string;
+    /** One-line explanation the engine shows for this setting. */
+    readonly description?: string;
+    /**
+     * True when the values this setting offers are resolved as it is read rather
+     * than declared: what is installed, what the running session supports. The
+     * boundary resolves them; nothing above it supplies them.
+     */
+    readonly resolvedWhenRead?: boolean;
+    /** Smallest value a numeric setting accepts, when the engine states one. */
+    readonly minimum?: number;
+    /** Largest value a numeric setting accepts, when the engine states one. */
+    readonly maximum?: number;
+    /**
+     * Flags a structured setting offers. Declared by the source rather than read
+     * from the stored value, so an unset flag still has a row and a default.
+     */
+    readonly flags?: readonly AgentSettingFlag[];
+}
+export interface AgentSettingFlag {
+    readonly key: string;
+    readonly label: string;
+    readonly description: string;
+    /** Value to show when the stored object says nothing about this flag. */
+    readonly fallback: boolean | string;
+    /**
+     * The values a keyed part may take, when it is a choice rather than a toggle. The first
+     * choice equal to `fallback` means "unset": writing it removes the key from the record.
+     */
+    readonly choices?: readonly string[];
+}
+export interface AgentResourceDescriptor {
+    readonly id: string;
+    readonly kind: "command" | "prompt" | "skill" | "extension" | "other";
+    readonly label: string;
+    readonly metadata: AgentJsonValue;
+}
+export interface AgentThemeDescriptor {
+    readonly id: string;
+    readonly label: string;
+    readonly tokens: Readonly<Record<string, string>>;
+}
+export interface AgentUiContribution {
+    readonly id: string;
+    readonly slot: "transcript" | "tool" | "editor" | "status" | "dialog" | "overlay" | "unknown";
+    readonly version: number;
+    readonly payload: AgentJsonValue;
+}
+export type AgentFailureCategory = "configuration" | "authentication" | "authorization" | "network" | "rate-limit" | "context-limit" | "tool" | "cancelled" | "engine" | "unknown";
+export interface AgentFailure {
+    readonly category: AgentFailureCategory;
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly details: AgentJsonValue;
+}
+export interface AgentDomainCapabilities {
+    readonly messageContent: readonly AgentMessageContent["kind"][];
+    readonly tools: readonly ("discovery" | "invocation" | "streaming-results")[];
+    readonly usage: readonly ("tokens" | "cache" | "cost")[];
+    readonly models: readonly ("discovery" | "selection" | "thinking-level")[];
+    readonly settings: readonly ("read" | "write")[];
+    readonly resources: readonly ("commands" | "prompts" | "skills" | "extensions" | "themes")[];
+    readonly uiContributions: readonly AgentUiContribution["slot"][];
+}

package/dist/contracts/agent-engine/index.d.ts

@@ -0,0 +1,11 @@
+export { assertAgentServicePorts } from "./capability-ports.js";
+export type { AgentAuthenticationPort, AgentExtensionBinding, AgentExtensionCommand, AgentExtensionFailure, AgentExtensionPort, AgentModelPort, AgentResourcesPort, AgentServicePorts, AgentSessionMetadata, AgentSettingsPort, AgentWorkflowDescriptor, AgentWorkflowPort, } from "./capability-ports.js";
+export type { AgentDomainCapabilities, AgentFailure, AgentFailureCategory, AgentJsonValue, AgentMessage, AgentMessageContent, AgentModelDescriptor, AgentResourceDescriptor, AgentSettingApplicationBoundary, AgentSettingChangeOutcome, AgentSettingDescriptor, AgentSettingFlag, AgentSettingOwner, AgentThemeDescriptor, AgentToolDescriptor, AgentUiContribution, AgentUsage, } from "./domain.js";
+export { assertAgentDomainCapabilities, assertAgentFailure, assertAgentMessage, assertAgentMessageContent, assertAgentModelDescriptor, assertAgentResourceDescriptor, assertAgentSettingDescriptor, assertAgentThemeDescriptor, assertAgentToolDescriptor, assertAgentUiContribution, assertAgentUsage, } from "./domain-validation.js";
+export { AGENT_ENGINE_CONTRACT_VERSION } from "./model.js";
+export type { AgentCapabilityContract, AgentCommand, AgentCommandCapability, AgentCommandId, AgentCommandOutcome, AgentEvent, AgentEventCapability, AgentEventSequence, AgentSessionId, AgentSessionLifecycle, AgentSnapshot, } from "./model.js";
+export { agentPackageOutcome, assertAgentPackagesPort } from "./package-ports.js";
+export type { AgentPackageDescriptor, AgentPackageDiagnostic, AgentPackageOperation, AgentPackageOutcome, AgentPackageProgress, AgentPackageStatus, AgentPackagesPort, AgentPackagesPortInput, } from "./package-ports.js";
+export type { AgentEnginePort, AgentSessionPort } from "./ports.js";
+export { assertAgentCapabilityContract, assertAgentCommand, assertAgentEvent, assertAgentSnapshot } from "./validation.js";
+export { decodeAgentCommand, decodeAgentEvent, decodeAgentSnapshot, encodeAgentCommand, encodeAgentEvent, encodeAgentSnapshot } from "./serialization.js";

package/dist/contracts/agent-engine/index.js

@@ -0,0 +1,6 @@
+export { assertAgentServicePorts } from "./capability-ports.js";
+export { assertAgentDomainCapabilities, assertAgentFailure, assertAgentMessage, assertAgentMessageContent, assertAgentModelDescriptor, assertAgentResourceDescriptor, assertAgentSettingDescriptor, assertAgentThemeDescriptor, assertAgentToolDescriptor, assertAgentUiContribution, assertAgentUsage, } from "./domain-validation.js";
+export { AGENT_ENGINE_CONTRACT_VERSION } from "./model.js";
+export { agentPackageOutcome, assertAgentPackagesPort } from "./package-ports.js";
+export { assertAgentCapabilityContract, assertAgentCommand, assertAgentEvent, assertAgentSnapshot } from "./validation.js";
+export { decodeAgentCommand, decodeAgentEvent, decodeAgentSnapshot, encodeAgentCommand, encodeAgentEvent, encodeAgentSnapshot } from "./serialization.js";

package/dist/contracts/agent-engine/package-ports.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Extension packages are managed outside any session: the command that installs
+ * one runs before the runtime exists, against a profile root chosen by the caller
+ * rather than by whatever session happens to be open. So this port stands apart
+ * from the session-scoped service ports and names only what a package operation
+ * needs — a root, a source, and an outcome a caller can render without knowing
+ * which engine performed it.
+ */
+export type AgentPackageOperation = "install" | "remove" | "update" | "refresh-models" | "list";
+/**
+ * Why an operation ended, kept separate from the prose so callers can branch on
+ * it. `not-found` is the one failure an engine can state structurally — the source
+ * is not configured in this profile — rather than only in a message.
+ */
+export type AgentPackageStatus = "completed" | "not-found" | "failed";
+export interface AgentPackageDescriptor {
+    readonly source: string;
+    readonly installedPath: string | null;
+    /** True when the profile enables only part of what the package provides. */
+    readonly filtered: boolean;
+}
+export interface AgentPackageOutcome {
+    readonly operation: AgentPackageOperation;
+    readonly status: AgentPackageStatus;
+    readonly source: string | null;
+    readonly packages: readonly AgentPackageDescriptor[];
+    readonly detail: string | null;
+}
+export interface AgentPackageProgress {
+    readonly operation: AgentPackageOperation;
+    readonly message: string;
+}
+export interface AgentPackagesPort {
+    readonly capabilities: {
+        readonly install: boolean;
+        readonly remove: boolean;
+        readonly update: boolean;
+        readonly refreshModels: boolean;
+    };
+    /** Absolute profile root every operation of this port acts on. */
+    readonly profileRoot: string;
+    list(): Promise<AgentPackageOutcome>;
+    install(source: string): Promise<AgentPackageOutcome>;
+    remove(source: string): Promise<AgentPackageOutcome>;
+    update(source?: string): Promise<AgentPackageOutcome>;
+    refreshModels(): Promise<AgentPackageOutcome>;
+}
+/** Recoverable operation diagnostics retain the engine's visible detail and order. */
+export interface AgentPackageDiagnostic {
+    readonly message: string;
+    readonly detail?: string;
+}
+export interface AgentPackagesPortInput {
+    readonly profileRoot: string;
+    readonly cwd: string;
+    readonly onProgress?: (progress: AgentPackageProgress) => void;
+    readonly onDiagnostic?: (diagnostic: AgentPackageDiagnostic) => void;
+}
+export declare function assertAgentPackagesPort(port: AgentPackagesPort): void;
+export declare function agentPackageOutcome(operation: AgentPackageOperation, status: AgentPackageStatus, detail?: string | null, source?: string | null, packages?: readonly AgentPackageDescriptor[]): AgentPackageOutcome;

package/dist/contracts/agent-engine/ports.js

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