@adecore/agent-contracts 0.0.1 → 0.17.0-beta.2

package/dist/envelope.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+export declare const ErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type WireError = z.infer<typeof ErrorSchema>;
+export declare const RequestSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    payload: z.ZodUnknown;
+}, z.core.$strip>;
+export type Request = z.infer<typeof RequestSchema>;
+export declare const ReplyOkSchema: z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodLiteral<true>;
+    result: z.ZodUnknown;
+}, z.core.$strip>;
+export type ReplyOk = z.infer<typeof ReplyOkSchema>;
+export declare const ReplyErrorSchema: z.ZodObject<{
+    id: z.ZodNullable<z.ZodString>;
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ReplyError = z.infer<typeof ReplyErrorSchema>;
+export declare const ReplySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodLiteral<true>;
+    result: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodNullable<z.ZodString>;
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>], "ok">;
+export type Reply = z.infer<typeof ReplySchema>;
+export declare const EventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"event">;
+    event: z.ZodString;
+    payload: z.ZodUnknown;
+}, z.core.$strip>;
+export type Event = z.infer<typeof EventSchema>;
+export declare const ServerFrameSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodLiteral<true>;
+    result: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodNullable<z.ZodString>;
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>], "ok">, z.ZodObject<{
+    type: z.ZodLiteral<"event">;
+    event: z.ZodString;
+    payload: z.ZodUnknown;
+}, z.core.$strip>]>;
+export type ServerFrame = z.infer<typeof ServerFrameSchema>;
+export type ParseResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function parseRequest(input: unknown): ParseResult<Request>;
+export declare function parseServerFrame(input: unknown): ParseResult<ServerFrame>;

package/dist/envelope.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export const ErrorSchema = z.object({
+    code: z.string().min(1),
+    message: z.string()
+});
+export const RequestSchema = z.object({
+    id: z.string().min(1),
+    type: z.string().min(1),
+    payload: z.unknown()
+});
+export const ReplyOkSchema = z.object({
+    id: z.string().min(1),
+    ok: z.literal(true),
+    result: z.unknown()
+});
+// The id is nullable so the server can still answer a frame it could not parse at all.
+export const ReplyErrorSchema = z.object({
+    id: z.string().min(1).nullable(),
+    ok: z.literal(false),
+    error: ErrorSchema
+});
+export const ReplySchema = z.discriminatedUnion('ok', [ReplyOkSchema, ReplyErrorSchema]);
+export const EventSchema = z.object({
+    type: z.literal('event'),
+    event: z.string().min(1),
+    payload: z.unknown()
+});
+export const ServerFrameSchema = z.union([ReplySchema, EventSchema]);
+function toResult(parsed) {
+    if (parsed.success) {
+        return { ok: true, value: parsed.data };
+    }
+    return { ok: false, message: z.prettifyError(parsed.error) };
+}
+export function parseRequest(input) {
+    return toResult(RequestSchema.safeParse(input));
+}
+export function parseServerFrame(input) {
+    return toResult(ServerFrameSchema.safeParse(input));
+}

package/dist/ids.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+export declare const SessionIdSchema: z.ZodString;
+export type SessionId = z.infer<typeof SessionIdSchema>;

package/dist/ids.js

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+// The client picks the id (its node id), so the only rule is that it is not empty.
+export const SessionIdSchema = z.string().min(1);

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from './agent.ts';
+export * from './chat.ts';
+export * from './envelope.ts';
+export * from './ids.ts';
+export * from './model.ts';
+export * from './protocol.ts';
+export * from './provider-accounts.ts';
+export * from './task.ts';
+export * from './text.ts';
+export * from './usage.ts';
+export * from './worktree.ts';
+export type * from './port.ts';

package/dist/index.js

@@ -0,0 +1,11 @@
+export * from './agent.js';
+export * from './chat.js';
+export * from './envelope.js';
+export * from './ids.js';
+export * from './model.js';
+export * from './protocol.js';
+export * from './provider-accounts.js';
+export * from './task.js';
+export * from './text.js';
+export * from './usage.js';
+export * from './worktree.js';

package/dist/model.d.ts

@@ -0,0 +1,282 @@
+import { z } from 'zod';
+export declare const ModelOptionChoiceSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ModelOptionChoice = z.infer<typeof ModelOptionChoiceSchema>;
+export declare const ModelOptionDescriptorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodLiteral<"select">;
+    choices: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    defaultChoice: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodLiteral<"boolean">;
+    defaultValue: z.ZodBoolean;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type ModelOptionDescriptor = z.infer<typeof ModelOptionDescriptorSchema>;
+export declare const ModelInfoSchema: z.ZodObject<{
+    slug: z.ZodString;
+    name: z.ZodString;
+    badge: z.ZodOptional<z.ZodString>;
+    legacy: z.ZodBoolean;
+    isDefault: z.ZodBoolean;
+    options: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodLiteral<"select">;
+        choices: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        defaultChoice: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodLiteral<"boolean">;
+        defaultValue: z.ZodBoolean;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>;
+export type ModelInfo = z.infer<typeof ModelInfoSchema>;
+export declare const ModelSelectionSchema: z.ZodObject<{
+    model: z.ZodString;
+    options: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
+}, z.core.$strip>;
+export type ModelSelection = z.infer<typeof ModelSelectionSchema>;
+export declare const ModelCatalogProfileSchema: z.ZodObject<{
+    options: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodLiteral<"select">;
+        choices: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        defaultChoice: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodLiteral<"boolean">;
+        defaultValue: z.ZodBoolean;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>;
+    contextWindowTokens: z.ZodRecord<z.ZodString, z.ZodNumber>;
+}, z.core.$strip>;
+export type ModelCatalogProfile = z.infer<typeof ModelCatalogProfileSchema>;
+export declare const ModelCatalogEntrySchema: z.ZodObject<{
+    slug: z.ZodString;
+    name: z.ZodString;
+    badge: z.ZodOptional<z.ZodString>;
+    profile: z.ZodString;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    legacy: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ModelCatalogEntry = z.infer<typeof ModelCatalogEntrySchema>;
+export declare const ModelCatalogDataSchema: z.ZodObject<{
+    updatedAt: z.ZodISODateTime;
+    defaultModel: z.ZodString;
+    profiles: z.ZodRecord<z.ZodString, z.ZodObject<{
+        options: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            type: z.ZodLiteral<"select">;
+            choices: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            defaultChoice: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            type: z.ZodLiteral<"boolean">;
+            defaultValue: z.ZodBoolean;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "type">>;
+        contextWindowTokens: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strip>>;
+    models: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        name: z.ZodString;
+        badge: z.ZodOptional<z.ZodString>;
+        profile: z.ZodString;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        legacy: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ModelCatalogData = z.infer<typeof ModelCatalogDataSchema>;
+export declare const RuntimeModeSchema: z.ZodEnum<{
+    auto: "auto";
+    "auto-accept-edits": "auto-accept-edits";
+    "full-access": "full-access";
+    supervised: "supervised";
+}>;
+export type RuntimeMode = z.infer<typeof RuntimeModeSchema>;
+export declare const ProviderCapabilitiesSchema: z.ZodObject<{
+    chat: z.ZodBoolean;
+    terminal: z.ZodBoolean;
+    hooks: z.ZodBoolean;
+    streamsToolOutput: z.ZodBoolean;
+    diffs: z.ZodEnum<{
+        "before-after": "before-after";
+        none: "none";
+        unified: "unified";
+    }>;
+    attachments: z.ZodBoolean;
+    mentions: z.ZodBoolean;
+    denyReason: z.ZodBoolean;
+    allowAlways: z.ZodBoolean;
+    asyncQuestions: z.ZodBoolean;
+    compaction: z.ZodEnum<{
+        native: "native";
+        none: "none";
+        prompt: "prompt";
+    }>;
+    reportsCost: z.ZodBoolean;
+    reportsContextWindow: z.ZodBoolean;
+    reportsThinking: z.ZodBoolean;
+    slashCommands: z.ZodBoolean;
+}, z.core.$strip>;
+export type ProviderCapabilities = z.infer<typeof ProviderCapabilitiesSchema>;
+export declare const ProviderInfoSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        apple: "apple";
+        claude: "claude";
+        codex: "codex";
+        copilot: "copilot";
+        gemini: "gemini";
+    }>;
+    name: z.ZodString;
+    installed: z.ZodBoolean;
+    version: z.ZodNullable<z.ZodString>;
+    models: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        name: z.ZodString;
+        badge: z.ZodOptional<z.ZodString>;
+        legacy: z.ZodBoolean;
+        isDefault: z.ZodBoolean;
+        options: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            type: z.ZodLiteral<"select">;
+            choices: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            defaultChoice: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            type: z.ZodLiteral<"boolean">;
+            defaultValue: z.ZodBoolean;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "type">>;
+    }, z.core.$strip>>;
+    defaultModel: z.ZodNullable<z.ZodString>;
+    capabilities: z.ZodObject<{
+        chat: z.ZodBoolean;
+        terminal: z.ZodBoolean;
+        hooks: z.ZodBoolean;
+        streamsToolOutput: z.ZodBoolean;
+        diffs: z.ZodEnum<{
+            "before-after": "before-after";
+            none: "none";
+            unified: "unified";
+        }>;
+        attachments: z.ZodBoolean;
+        mentions: z.ZodBoolean;
+        denyReason: z.ZodBoolean;
+        allowAlways: z.ZodBoolean;
+        asyncQuestions: z.ZodBoolean;
+        compaction: z.ZodEnum<{
+            native: "native";
+            none: "none";
+            prompt: "prompt";
+        }>;
+        reportsCost: z.ZodBoolean;
+        reportsContextWindow: z.ZodBoolean;
+        reportsThinking: z.ZodBoolean;
+        slashCommands: z.ZodBoolean;
+    }, z.core.$strip>;
+    resumeCommand: z.ZodString;
+}, z.core.$strip>;
+export type ProviderInfo = z.infer<typeof ProviderInfoSchema>;
+export declare const ProviderListResultSchema: z.ZodObject<{
+    providers: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            apple: "apple";
+            claude: "claude";
+            codex: "codex";
+            copilot: "copilot";
+            gemini: "gemini";
+        }>;
+        name: z.ZodString;
+        installed: z.ZodBoolean;
+        version: z.ZodNullable<z.ZodString>;
+        models: z.ZodArray<z.ZodObject<{
+            slug: z.ZodString;
+            name: z.ZodString;
+            badge: z.ZodOptional<z.ZodString>;
+            legacy: z.ZodBoolean;
+            isDefault: z.ZodBoolean;
+            options: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                type: z.ZodLiteral<"select">;
+                choices: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    label: z.ZodString;
+                    description: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                defaultChoice: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                type: z.ZodLiteral<"boolean">;
+                defaultValue: z.ZodBoolean;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>], "type">>;
+        }, z.core.$strip>>;
+        defaultModel: z.ZodNullable<z.ZodString>;
+        capabilities: z.ZodObject<{
+            chat: z.ZodBoolean;
+            terminal: z.ZodBoolean;
+            hooks: z.ZodBoolean;
+            streamsToolOutput: z.ZodBoolean;
+            diffs: z.ZodEnum<{
+                "before-after": "before-after";
+                none: "none";
+                unified: "unified";
+            }>;
+            attachments: z.ZodBoolean;
+            mentions: z.ZodBoolean;
+            denyReason: z.ZodBoolean;
+            allowAlways: z.ZodBoolean;
+            asyncQuestions: z.ZodBoolean;
+            compaction: z.ZodEnum<{
+                native: "native";
+                none: "none";
+                prompt: "prompt";
+            }>;
+            reportsCost: z.ZodBoolean;
+            reportsContextWindow: z.ZodBoolean;
+            reportsThinking: z.ZodBoolean;
+            slashCommands: z.ZodBoolean;
+        }, z.core.$strip>;
+        resumeCommand: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ProviderListResult = z.infer<typeof ProviderListResultSchema>;
+export declare function resumeCommandFor(template: string, agentSessionId: string, flags?: string[]): string;

package/dist/model.js

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+import { AgentKindSchema } from './agent.js';
+// Options a model exposes (effort, context window, thinking). Generic descriptors instead of
+// per-provider enums: a new model is a catalog entry, not a code change.
+export const ModelOptionChoiceSchema = z.object({
+    id: z.string().min(1),
+    label: z.string(),
+    description: z.string().optional()
+});
+export const ModelOptionDescriptorSchema = z.discriminatedUnion('type', [
+    z.object({
+        id: z.string().min(1),
+        label: z.string(),
+        type: z.literal('select'),
+        choices: z.array(ModelOptionChoiceSchema).min(1),
+        defaultChoice: z.string()
+    }),
+    z.object({
+        id: z.string().min(1),
+        label: z.string(),
+        type: z.literal('boolean'),
+        defaultValue: z.boolean(),
+        // The line under the label in the picker: what turning it on costs or asks for.
+        description: z.string().optional()
+    })
+]);
+export const ModelInfoSchema = z.object({
+    slug: z.string().min(1),
+    name: z.string(),
+    badge: z.string().optional(),
+    legacy: z.boolean(),
+    isDefault: z.boolean(),
+    options: z.array(ModelOptionDescriptorSchema)
+});
+export const ModelSelectionSchema = z.object({
+    model: z.string().min(1),
+    options: z.record(z.string(), z.union([z.string(), z.boolean()]))
+});
+// A slug ends up on a CLI's command line, so it never starts with a dash and carries no brackets.
+const ModelSlugSchema = z.string().regex(/^[a-z0-9][a-z0-9._-]*$/, 'Expected a model slug');
+export const ModelCatalogProfileSchema = z.object({
+    options: z.array(ModelOptionDescriptorSchema),
+    // Context size per value of the `contextWindow` option, or `*` when the model has one size.
+    contextWindowTokens: z.record(z.string(), z.number().int().positive())
+});
+export const ModelCatalogEntrySchema = z.object({
+    slug: ModelSlugSchema,
+    name: z.string().min(1),
+    badge: z.string().optional(),
+    profile: z.string().min(1),
+    aliases: z.array(z.string().min(1)).optional(),
+    legacy: z.boolean().optional()
+});
+/*
+ * The models one provider offers, as a host ships them and as a catalog service hands out a newer
+ * copy. `updatedAt` orders the two, so a copy older than the one a host shipped with is never taken.
+ */
+export const ModelCatalogDataSchema = z
+    .object({
+    updatedAt: z.iso.datetime(),
+    defaultModel: ModelSlugSchema,
+    profiles: z.record(z.string(), ModelCatalogProfileSchema),
+    models: z.array(ModelCatalogEntrySchema).min(1)
+})
+    .refine((data) => data.models.every((model) => data.profiles[model.profile] !== undefined), 'Every model needs a profile the catalog has')
+    .refine((data) => data.models.some((model) => model.slug === data.defaultModel), 'The default model has to be one of the models');
+// The thread's permission policy, one vocabulary for every provider; each adapter maps it.
+export const RuntimeModeSchema = z.enum(['supervised', 'auto-accept-edits', 'auto', 'full-access']);
+// What a provider's CLI can do, so a client never offers what it would drop and the daemon
+// never asks for what the protocol has no room for. Read by the composer and the thread rows.
+export const ProviderCapabilitiesSchema = z.object({
+    // Where this CLI can be opened: as a chat node, as a terminal node, or both.
+    chat: z.boolean(),
+    terminal: z.boolean(),
+    // Whether the daemon understands this CLI's hooks; without them a node shows the session status only.
+    hooks: z.boolean(),
+    // Partial output while a tool call runs, for the live row under it.
+    streamsToolOutput: z.boolean(),
+    // How a file change reaches the thread: as a unified diff, as the text before and after, or not at all.
+    diffs: z.enum(['unified', 'before-after', 'none']),
+    attachments: z.boolean(),
+    mentions: z.boolean(),
+    // Whether a decline carries a reason for the agent.
+    denyReason: z.boolean(),
+    allowAlways: z.boolean(),
+    // A question the person may leave alone while the turn goes on.
+    asyncQuestions: z.boolean(),
+    // Folding the context: a call of its own, a slash command sent as a turn, or nothing.
+    compaction: z.enum(['native', 'prompt', 'none']),
+    reportsCost: z.boolean(),
+    reportsContextWindow: z.boolean(),
+    // Whether the CLI hands over what the model thought before it answered.
+    reportsThinking: z.boolean(),
+    slashCommands: z.boolean()
+});
+export const ProviderInfoSchema = z.object({
+    kind: AgentKindSchema,
+    name: z.string(),
+    installed: z.boolean(),
+    version: z.string().nullable(),
+    // Empty while the CLI is not installed or has no chat backend yet.
+    models: z.array(ModelInfoSchema),
+    defaultModel: z.string().nullable(),
+    capabilities: ProviderCapabilitiesSchema,
+    // What a terminal runs to continue one of this CLI's sessions. `{id}` stands for the session id
+    // and `{flags}` for the flags the launch carries, which is where in the line each CLI takes them.
+    resumeCommand: z.string()
+});
+export const ProviderListResultSchema = z.object({
+    providers: z.array(ProviderInfoSchema)
+});
+/*
+ * Fills a provider's resume template; the id is quoted so a shell takes it as one word. `{flags}` is
+ * a word of its own rather than a substring, since it stands for none, one or several words and a
+ * substitution would leave a double space behind where a launch carries no flags at all.
+ */
+export function resumeCommandFor(template, agentSessionId, flags = []) {
+    const id = `'${agentSessionId.replaceAll("'", `'\\''`)}'`;
+    return template
+        .split(' ')
+        .flatMap((word) => (word === '{flags}' ? flags : [word.replace('{id}', id)]))
+        .join(' ');
+}

package/dist/port.d.ts

@@ -0,0 +1,5 @@
+import type { Request, ServerFrame } from './envelope.ts';
+export interface FramePort {
+    send(frame: Request | ServerFrame): void;
+    onFrame(listener: (frame: unknown) => void): () => void;
+}

package/dist/port.js

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