@artinet/sdk/dist/types/a2a/a2a.d.ts

A TypeScript SDK for building collaborative AI agents.

/**
 * Copyright 2025 The Artinet Project
 * SPDX-License-Identifier: Apache-2.0
 */
import { AgentCard, Message, Task, AgentExtension, TaskQueryParams, TaskIdParams, MessageSendParams, SendMessageSuccessResult, PushNotificationConfig } from "@artinet/types/a2a";
import { core } from "../core/index.js";
import { z } from "zod/v4";
export type AgentCardParams = (Partial<AgentCard> & Required<Pick<AgentCard, "name">>) | string;
export declare const UpdateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
    role: z.ZodEnum<{
        user: "user";
        agent: "agent";
    }>;
    parts: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
        kind: z.ZodLiteral<"text">;
        text: z.ZodString;
    }, z.core.$strip>, z.ZodObject<{
        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
        kind: z.ZodLiteral<"file">;
        file: z.ZodUnion<readonly [z.ZodObject<{
            name: z.ZodOptional<z.ZodString>;
            mimeType: z.ZodOptional<z.ZodString>;
            bytes: z.ZodString;
            uri: z.ZodOptional<z.ZodNever>;
        }, z.core.$strip>, z.ZodObject<{
            name: z.ZodOptional<z.ZodString>;
            mimeType: z.ZodOptional<z.ZodString>;
            uri: z.ZodString;
            bytes: z.ZodOptional<z.ZodNever>;
        }, z.core.$strip>]>;
    }, z.core.$strip>, z.ZodObject<{
        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
        kind: z.ZodLiteral<"data">;
        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
    }, z.core.$strip>]>>;
    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
    extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
    referenceTaskIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
    messageId: z.ZodString;
    taskId: z.ZodOptional<z.ZodString>;
    contextId: z.ZodOptional<z.ZodString>;
    kind: z.ZodLiteral<"message">;
}, z.core.$strip>, z.ZodObject<{
    id: z.ZodString;
    contextId: z.ZodString;
    status: z.ZodObject<{
        state: z.ZodEnum<{
            unknown: "unknown";
            submitted: "submitted";
            working: "working";
            "input-required": "input-required";
            completed: "completed";
            canceled: "canceled";
            failed: "failed";
            rejected: "rejected";
            "auth-required": "auth-required";
        }>;
        message: z.ZodOptional<z.ZodObject<{
            role: z.ZodEnum<{
                user: "user";
                agent: "agent";
            }>;
            parts: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                kind: z.ZodLiteral<"text">;
                text: z.ZodString;
            }, z.core.$strip>, z.ZodObject<{
                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                kind: z.ZodLiteral<"file">;
                file: z.ZodUnion<readonly [z.ZodObject<{
                    name: z.ZodOptional<z.ZodString>;
                    mimeType: z.ZodOptional<z.ZodString>;
                    bytes: z.ZodString;
                    uri: z.ZodOptional<z.ZodNever>;
                }, z.core.$strip>, z.ZodObject<{
                    name: z.ZodOptional<z.ZodString>;
                    mimeType: z.ZodOptional<z.ZodString>;
                    uri: z.ZodString;
                    bytes: z.ZodOptional<z.ZodNever>;
                }, z.core.$strip>]>;
            }, z.core.$strip>, z.ZodObject<{
                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                kind: z.ZodLiteral<"data">;
                data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
            }, z.core.$strip>]>>;
            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
            extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
            referenceTaskIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
            messageId: z.ZodString;
            taskId: z.ZodOptional<z.ZodString>;
            contextId: z.ZodOptional<z.ZodString>;
            kind: z.ZodLiteral<"message">;
        }, z.core.$strip>>;
        timestamp: z.ZodOptional<z.ZodISODateTime>;
    }, z.core.$strip>;
    history: z.ZodOptional<z.ZodArray<z.ZodObject<{
        role: z.ZodEnum<{
            user: "user";
            agent: "agent";
        }>;
        parts: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
            kind: z.ZodLiteral<"text">;
            text: z.ZodString;
        }, z.core.$strip>, z.ZodObject<{
            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
            kind: z.ZodLiteral<"file">;
            file: z.ZodUnion<readonly [z.ZodObject<{
                name: z.ZodOptional<z.ZodString>;
                mimeType: z.ZodOptional<z.ZodString>;
                bytes: z.ZodString;
                uri: z.ZodOptional<z.ZodNever>;
            }, z.core.$strip>, z.ZodObject<{
                name: z.ZodOptional<z.ZodString>;
                mimeType: z.ZodOptional<z.ZodString>;
                uri: z.ZodString;
                bytes: z.ZodOptional<z.ZodNever>;
            }, z.core.$strip>]>;
        }, z.core.$strip>, z.ZodObject<{
            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
            kind: z.ZodLiteral<"data">;
            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
        }, z.core.$strip>]>>;
        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
        extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
        referenceTaskIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
        messageId: z.ZodString;
        taskId: z.ZodOptional<z.ZodString>;
        contextId: z.ZodOptional<z.ZodString>;
        kind: z.ZodLiteral<"message">;
    }, z.core.$strip>>>;
    artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
        artifactId: z.ZodString;
        name: z.ZodOptional<z.ZodString>;
        description: z.ZodOptional<z.ZodString>;
        parts: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
            kind: z.ZodLiteral<"text">;
            text: z.ZodString;
        }, z.core.$strip>, z.ZodObject<{
            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
            kind: z.ZodLiteral<"file">;
            file: z.ZodUnion<readonly [z.ZodObject<{
                name: z.ZodOptional<z.ZodString>;
                mimeType: z.ZodOptional<z.ZodString>;
                bytes: z.ZodString;
                uri: z.ZodOptional<z.ZodNever>;
            }, z.core.$strip>, z.ZodObject<{
                name: z.ZodOptional<z.ZodString>;
                mimeType: z.ZodOptional<z.ZodString>;
                uri: z.ZodString;
                bytes: z.ZodOptional<z.ZodNever>;
            }, z.core.$strip>]>;
        }, z.core.$strip>, z.ZodObject<{
            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
            kind: z.ZodLiteral<"data">;
            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
        }, z.core.$strip>]>>;
        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
        extension: z.ZodOptional<z.ZodArray<z.ZodString>>;
    }, z.core.$strip>>>;
    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
    kind: z.ZodLiteral<"task">;
}, z.core.$strip>, z.ZodObject<{
    taskId: z.ZodString;
    contextId: z.ZodString;
    kind: z.ZodLiteral<"status-update">;
    status: z.ZodObject<{
        state: z.ZodEnum<{
            unknown: "unknown";
            submitted: "submitted";
            working: "working";
            "input-required": "input-required";
            completed: "completed";
            canceled: "canceled";
            failed: "failed";
            rejected: "rejected";
            "auth-required": "auth-required";
        }>;
        message: z.ZodOptional<z.ZodObject<{
            role: z.ZodEnum<{
                user: "user";
                agent: "agent";
            }>;
            parts: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                kind: z.ZodLiteral<"text">;
                text: z.ZodString;
            }, z.core.$strip>, z.ZodObject<{
                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                kind: z.ZodLiteral<"file">;
                file: z.ZodUnion<readonly [z.ZodObject<{
                    name: z.ZodOptional<z.ZodString>;
                    mimeType: z.ZodOptional<z.ZodString>;
                    bytes: z.ZodString;
                    uri: z.ZodOptional<z.ZodNever>;
                }, z.core.$strip>, z.ZodObject<{
                    name: z.ZodOptional<z.ZodString>;
                    mimeType: z.ZodOptional<z.ZodString>;
                    uri: z.ZodString;
                    bytes: z.ZodOptional<z.ZodNever>;
                }, z.core.$strip>]>;
            }, z.core.$strip>, z.ZodObject<{
                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                kind: z.ZodLiteral<"data">;
                data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
            }, z.core.$strip>]>>;
            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
            extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
            referenceTaskIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
            messageId: z.ZodString;
            taskId: z.ZodOptional<z.ZodString>;
            contextId: z.ZodOptional<z.ZodString>;
            kind: z.ZodLiteral<"message">;
        }, z.core.$strip>>;
        timestamp: z.ZodOptional<z.ZodISODateTime>;
    }, z.core.$strip>;
    final: z.ZodBoolean;
    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
}, z.core.$strip>, z.ZodObject<{
    taskId: z.ZodString;
    contextId: z.ZodString;
    kind: z.ZodLiteral<"artifact-update">;
    artifact: z.ZodObject<{
        artifactId: z.ZodString;
        name: z.ZodOptional<z.ZodString>;
        description: z.ZodOptional<z.ZodString>;
        parts: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
            kind: z.ZodLiteral<"text">;
            text: z.ZodString;
        }, z.core.$strip>, z.ZodObject<{
            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
            kind: z.ZodLiteral<"file">;
            file: z.ZodUnion<readonly [z.ZodObject<{
                name: z.ZodOptional<z.ZodString>;
                mimeType: z.ZodOptional<z.ZodString>;
                bytes: z.ZodString;
                uri: z.ZodOptional<z.ZodNever>;
            }, z.core.$strip>, z.ZodObject<{
                name: z.ZodOptional<z.ZodString>;
                mimeType: z.ZodOptional<z.ZodString>;
                uri: z.ZodString;
                bytes: z.ZodOptional<z.ZodNever>;
            }, z.core.$strip>]>;
        }, z.core.$strip>, z.ZodObject<{
            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
            kind: z.ZodLiteral<"data">;
            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
        }, z.core.$strip>]>>;
        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
        extension: z.ZodOptional<z.ZodArray<z.ZodString>>;
    }, z.core.$strip>;
    append: z.ZodOptional<z.ZodBoolean>;
    lastChunk: z.ZodOptional<z.ZodBoolean>;
    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
}, z.core.$strip>]>;
export type Update = z.output<typeof UpdateSchema>;
export type Engine = (context: Context) => AsyncGenerator<Update, void, unknown>;
export interface BaseContext extends core.Context<Task> {
    readonly service: Service;
    /**
     * Considering ommit OnStart & OnComplete from Context consumers.
     * That way the user cannot inadvertently trigger a start/completion out of band.
     */
    readonly publisher: EventPublisher;
}
export interface Context extends BaseContext {
    readonly taskId: string;
    readonly userMessage: Message;
    readonly messages: MessageConsumerProxy;
    extensions?: AgentExtension[];
    references?: Task[];
    userId?: string;
    getTask: () => Promise<Task>;
}
export type ContextParams = Omit<BaseContext, "publisher" | "isCancelled" | "getState" | "abortSignal"> & Omit<Partial<Context>, "userMessage" | "taskId"> & {
    messenger: MessageConsumerProxy;
    task: Task;
    overrides?: Partial<Omit<EventConsumer, "contextId">>;
};
export interface Contexts extends core.Contexts<Context> {
    create: (params: ContextParams) => Promise<Context>;
    list: () => Promise<Context[]>;
}
export interface Tasks extends core.Manager<Task> {
    update: (context: Context, update: Update) => Promise<Task>;
    create: (params: Partial<Task>) => Promise<Task>;
    has: (id: string) => Promise<boolean>;
}
export interface Cancellations extends Omit<core.Manager<void>, "get"> {
    has: (id: string) => Promise<boolean>;
}
export interface Connections extends Omit<core.Manager<void>, "get"> {
}
export interface Notifier {
    notify: (task: Task, update: Update, context?: Context) => Promise<void>;
    register: (taskId: string, config: PushNotificationConfig) => Promise<void>;
}
export type ServiceOptions = Pick<ContextParams, "userId" | "extensions"> & {
    task?: Task;
    signal?: AbortSignal;
    notifier?: Notifier;
};
export interface Handles {
    getTask: (input: TaskQueryParams, context: Context) => Promise<Task>;
    cancelTask: (input: TaskIdParams, context: Context) => Promise<Task>;
    sendMessage: (message: MessageSendParams, context: Context) => Promise<SendMessageSuccessResult>;
    /**
     * @deprecated Use sendMessageStream instead
     */
    streamMessage: (message: MessageSendParams, context: Context) => AsyncGenerator<Update>;
    sendMessageStream: (message: MessageSendParams, context: Context) => AsyncGenerator<Update>;
    resubscribe: (input: TaskIdParams, context: Context) => AsyncGenerator<Update>;
}
export interface RequestHandler {
    getTask: (input: TaskQueryParams, options?: ServiceOptions) => Promise<Task>;
    cancelTask: (input: TaskIdParams, options?: ServiceOptions) => Promise<Task>;
    sendMessage: (message: MessageSendParams, options?: ServiceOptions) => Promise<SendMessageSuccessResult>;
    /**
     * @deprecated Use sendMessageStream instead
     */
    streamMessage: (message: MessageSendParams, options?: ServiceOptions) => AsyncGenerator<Update>;
    sendMessageStream: (message: MessageSendParams, options?: ServiceOptions) => AsyncGenerator<Update>;
    resubscribe: (input: TaskIdParams, options?: ServiceOptions) => AsyncGenerator<Update>;
    getAgentCard: () => Promise<AgentCard>;
}
export interface Stream {
    readonly contextId: string;
    isAlive: boolean;
    kill: () => Promise<void>;
    updates: Update[];
    context: Context;
    run: (params: {
        service: Service;
    }) => AsyncGenerator<Update>;
    subscribe: () => AsyncGenerator<Update>;
}
export interface Streams extends Omit<core.Manager<Stream>, "set"> {
    create: (params: core.Optional<Stream> & {
        context: Context;
    }) => Promise<Stream>;
    has: (id: string) => Promise<boolean>;
}
export interface Service extends core.Service<{
    engine: Engine;
    context: Context;
}>, RequestHandler {
    readonly events?: Events;
    readonly connections: Connections;
    readonly cancellations: Cancellations;
    readonly tasks: Tasks;
    readonly contexts: Contexts;
    readonly streams: Streams;
    engine: Engine;
    agentCard: AgentCard;
}
export interface MessageProducer {
    isOpen: boolean;
    send: (message: MessageSendParams) => Promise<void>;
}
export type MessageMap = {
    message: [MessageSendParams];
    close: [];
};
export interface MessageConsumer extends core.Consumer<MessageSendParams, MessageMap> {
    message: MessageSendParams;
    messages: MessageSendParams[];
    close: () => Promise<void>;
    next: () => Promise<IteratorResult<MessageSendParams>>;
    return: (value: MessageSendParams) => Promise<IteratorResult<MessageSendParams>>;
}
export type MessageConsumerProxy = MessageConsumer & MessageSendParams;
export interface EventConsumer {
    readonly contextId: string;
    readonly onStart?: (context: Context) => Promise<Task>;
    readonly onCancel: (update: Update, current: Task) => Promise<void>;
    readonly onUpdate: (update: Update, current: Task) => Promise<Task>;
    readonly onError: (error: any, current: Task) => Promise<void>;
    onComplete: (current: Task) => Promise<void>;
}
export type Emissions = {
    start: [MessageSendParams, Task];
    cancel: [Update];
    update: [Task, Update];
    error: [any, Task];
    complete: [Task];
};
export interface EventPublisher extends Omit<EventConsumer, "onComplete" | "onCancel" | "onError" | "onUpdate">, core.Publisher<Emissions> {
    readonly onStart?: (context: Context) => Promise<Task>;
    readonly onCancel: (update: Update) => Promise<void>;
    readonly onUpdate: (update: Update) => Promise<Task>;
    readonly onError: (error: any) => Promise<void>;
    onComplete: () => Promise<void>;
}
export interface Events extends core.Manager<EventPublisher> {
    create: (params: core.Optional<EventPublisher>) => Promise<EventPublisher>;
}
export * from "@artinet/types/a2a";