@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

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 {};