@artinet/sdk 0.5.18 → 0.6.0-preview.2

package/dist/config/observability.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** //todo move to @artinet/sdk from core v0.1
+ * @fileoverview Zero-dependency observability interfaces for the Artinet ecosystem.
+ *
+ * Provides minimal interfaces for logging and tracing that consumers can implement
+ * with their preferred tools (Pino, Winston, OpenTelemetry, etc.).
+ *
+ * Design principles:
+ * - Zero runtime dependencies
+ * - No-op defaults for zero overhead when not configured
+ * - Environment agnostic (Node, Deno, Bun, edge, browser)
+ * - Consumer brings their own implementation
+ *
+ * @module utils/observability
+ */
+/**
+ * Minimal logger interface.
+ *
+ * Consumers provide their own implementation using their preferred
+ * logging library (Pino, Winston, console, etc.).
+ *
+ * Uses spread args for maximum compatibility - works naturally with
+ * console.log, Pino, Winston, and most logging libraries.
+ *
+ * @example
+ * ```typescript
+ * // Console implementation (just works)
+ * const logger: ILogger = console;
+ *
+ * // Pino implementation
+ * import pino from 'pino';
+ * const pinoLogger = pino();
+ *
+ * const logger: ILogger = {
+ *   debug: (msg, ...args) => pinoLogger.debug(Object.assign({}, ...args), msg),
+ *   info: (msg, ...args) => pinoLogger.info(Object.assign({}, ...args), msg),
+ *   warn: (msg, ...args) => pinoLogger.warn(Object.assign({}, ...args), msg),
+ *   error: (msg, ...args) => pinoLogger.error(Object.assign({}, ...args), msg),
+ * };
+ *
+ * // Winston implementation
+ * import winston from 'winston';
+ * const winstonLogger = winston.createLogger({ ... });
+ *
+ * const logger: ILogger = {
+ *   debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
+ *   info: (msg, ...args) => winstonLogger.info(msg, ...args),
+ *   warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
+ *   error: (msg, ...args) => winstonLogger.error(msg, ...args),
+ * };
+ * ```
+ */
+export interface ILogger {
+    /**
+     * Log level.
+     * @default "info"
+     */
+    level?: "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent";
+    /**
+     * Log debug-level message.
+     * @param msg - Log message
+     * @param args - Optional additional arguments (context, data, etc.)
+     */
+    debug(msg: string, ...args: unknown[]): void;
+    /**
+     * Log info-level message.
+     * @param msg - Log message
+     * @param args - Optional additional arguments (context, data, etc.)
+     */
+    info(msg: string, ...args: unknown[]): void;
+    /**
+     * Log warn-level message.
+     * @param msg - Log message
+     * @param args - Optional additional arguments (context, data, etc.)
+     */
+    warn(msg: string, ...args: unknown[]): void;
+    /**
+     * Log error-level message.
+     * @param msg - Log message
+     * @param err - Error to log
+     */
+    error(msg: string, err: unknown): void;
+    /**
+     * Set log level.
+     * @param level - Log level
+     */
+    setLevel?(level: "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent"): void;
+    /**
+     * Get log level.
+     * @returns Current log level or undefined if not set
+     */
+    getLevel?(): "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent";
+    /**
+     * Create child logger with bound context.
+     * @param context - Context to bind to the child logger
+     * @returns Child logger or undefined if not implemented
+     */
+    child?(context: Record<string, unknown>): ILogger;
+}
+/**
+ * Format error for logging.
+ * @param err - Error to format
+ * @returns Formatted error
+ */
+export declare function formatError(err: unknown): Record<string, unknown>;
+/**
+ * No-op logger implementation.
+ * Used when no logger is configured - zero overhead.
+ *
+ * @example
+ * ```typescript
+ * const logger = config.logger ?? noopLogger;
+ * logger.info('This does nothing if no logger configured');
+ * ```
+ */
+export declare const noopLogger: ILogger;

package/dist/config/observability.js

@@ -0,0 +1,35 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Format error for logging.
+ * @param err - Error to format
+ * @returns Formatted error
+ */
+export function formatError(err) {
+    if (err instanceof Error) {
+        return {
+            message: err.message,
+            stack: err.stack,
+            name: err.name,
+        };
+    }
+    return { error: String(err) };
+}
+/**
+ * No-op logger implementation.
+ * Used when no logger is configured - zero overhead.
+ *
+ * @example
+ * ```typescript
+ * const logger = config.logger ?? noopLogger;
+ * logger.info('This does nothing if no logger configured');
+ * ```
+ */
+export const noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};

package/dist/create/agent-builder.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+import { ArtifactUpdateParams, StatusUpdateParams, TaskParams } from "./task-builder.js";
+import { MessageParams } from "./message-builder.js";
+export interface BaseArguments {
+    message: A2A.MessageSendParams;
+    context: A2A.Context;
+    skip: () => Promise<void> | void;
+}
+export type BaseArgs = Record<string, unknown>;
+export type EmptyArgs = Record<string, never>;
+export type empty = EmptyArgs;
+export type bargs = BaseArgs;
+export type InputArguments<CarriedArguments extends BaseArgs = EmptyArgs> = BaseArguments & Partial<{
+    content: string;
+    args: CarriedArguments;
+}>;
+export type AcceptedKinds = "text" | "file" | "data" | "message" | "artifact-update" | "status-update" | "task";
+/**
+ * State will be inherited from the context, so we don't allow the user to pass those arguments back to us.
+ */
+export type Stateless<T> = T extends object ? Omit<T, "taskId" | "contextId"> : T;
+export type data = A2A.DataPart["data"];
+export type file = A2A.FilePart["file"];
+export type text = A2A.TextPart["text"];
+export type sMessage = Stateless<MessageParams>;
+export type sArtifact = Stateless<ArtifactUpdateParams>;
+export type sUpdate = Stateless<StatusUpdateParams>;
+export type sTask = Stateless<TaskParams>;
+export type AcceptedParts = data | file | text;
+export type AcceptedArrayValues = AcceptedParts | sUpdate | sArtifact;
+export type AcceptedReturnValues = AcceptedParts | sMessage | sArtifact | sUpdate | sTask;
+export type ReturnValue<Ret extends AcceptedReturnValues> = {
+    reply: Ret extends AcceptedArrayValues ? Array<Ret> | Ret : Ret;
+};
+export type ReturnAndCarry<Ret extends AcceptedReturnValues, Carried extends BaseArgs = EmptyArgs> = ReturnValue<Ret> & {
+    args: Carried;
+};
+export type Reply<Ret extends AcceptedReturnValues, Carried extends BaseArgs = EmptyArgs> = ReturnValue<Ret> | ReturnAndCarry<Ret, Carried> | Ret | (Ret extends AcceptedArrayValues ? Array<Ret> : never);
+export type rep<R extends AcceptedReturnValues, C extends BaseArgs> = Reply<R, C>;
+export type Invocable<Ret extends AcceptedReturnValues = A2A.TextPart["text"], Input extends BaseArgs = EmptyArgs, Carried extends BaseArgs = EmptyArgs, Response extends Reply<Ret, Carried> = Reply<Ret, Carried>> = (params: InputArguments<Input>) => Promise<Response> | Response;
+export type Step<Ret extends AcceptedReturnValues, Input extends BaseArgs = EmptyArgs, Carry extends BaseArgs = EmptyArgs> = Invocable<Ret, Input, Carry, Reply<Ret, Carry>>;
+export type Transform<Ret extends AcceptedReturnValues> = (payload: Ret | Array<Ret>, context: A2A.Context) => AsyncGenerator<A2A.Update, void, unknown>;
+export type Resolved<Ret extends AcceptedReturnValues = A2A.TextPart["text"], Input extends BaseArgs = EmptyArgs, Carried extends BaseArgs = EmptyArgs, Response extends Reply<Ret, Carried> = Reply<Ret, Carried>, Kind extends AcceptedKinds = "text"> = {
+    id: string;
+    step: Invocable<Ret, Input, Carried, Response>;
+    kind: Kind;
+    handler: Transform<Ret>;
+};
+export type inferCarry<Carried> = Carried extends ReturnAndCarry<any, infer Carry> ? Carry : EmptyArgs;
+export type inC<Carried> = Carried extends ReturnAndCarry<any, infer Carry> ? Carry : EmptyArgs;
+export interface AgentBuilder<Input extends BaseArgs = EmptyArgs> {
+    /**
+     * Add a step to the builder.
+     * @param step - The step to add.
+     * @returns A new builder with the step added.
+     */
+    addStep<Ret extends AcceptedReturnValues = A2A.TextPart["text"], Carried extends BaseArgs = EmptyArgs, Response extends Reply<Ret, Carried> = Reply<Ret, Carried>, Kind extends AcceptedKinds = "text">(step: Resolved<Ret, Input, Carried, Response, Kind>): AgentBuilder<inC<Response>>;
+}
+/**
+ * Carry Only Returns
+ * @internal
+ * Potential Upgrade:
+ * Currently enforce that args cant be passed back without a reply,
+ * but may allow carry only returns in the future.
+ *
+ * ```typescript
+ * type CarryOnly<Carried extends BaseArgs> = {
+ *   args: Carried;
+ * } & {
+ *   reply: never;
+ * };
+ * ```
+ */

package/dist/create/agent-builder.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};
+/**
+ * Carry Only Returns
+ * @internal
+ * Potential Upgrade:
+ * Currently enforce that args cant be passed back without a reply,
+ * but may allow carry only returns in the future.
+ *
+ * ```typescript
+ * type CarryOnly<Carried extends BaseArgs> = {
+ *   args: Carried;
+ * } & {
+ *   reply: never;
+ * };
+ * ```
+ */

package/dist/create/agentcard-builder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+export type AgentCardParams = (Partial<A2A.AgentCard> & Required<Pick<A2A.AgentCard, "name">>) | string;
+export declare const isAgentCardParams: (params: any) => params is AgentCardParams;
+export declare class AgentCard {
+    private readonly _agentCard;
+    constructor(params: Partial<A2A.AgentCard> & Required<Pick<A2A.AgentCard, "name">>);
+    get agentCard(): A2A.AgentCard;
+    static create(params: AgentCardParams): A2A.AgentCard;
+}
+/**
+ * @deprecated Use {@link card} instead
+ * @since 0.6.0
+ */
+export declare const AgentCardBuilder: typeof AgentCard;
+/**
+ * Convenience factory function for creating an {@link A2A.AgentCard} with default parameters.
+ *
+ * @returns New {@link A2A.AgentCard} with default parameters
+ * @defaults {
+ *   description: "An agent that can use the A2A protocol.",
+ *   url: "https://localhost:3000/a2a",
+ *   version: "0.0.0",
+ *   capabilities: {},
+ *   defaultInputModes: [],
+ *   defaultOutputModes: [],
+ *   skills: [],
+ *   preferredTransport: "JSONRPC",
+ * }
+ *
+ * @example
+ * ```typescript
+ * const agentCard = card("My Agent");
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export declare const card: typeof AgentCard.create;
+/**
+ * @deprecated Use {@link card} instead
+ * @since 0.6.0
+ */
+export declare const createAgentCard: typeof AgentCard.create;

package/dist/create/agentcard-builder.js

@@ -0,0 +1,66 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export const isAgentCardParams = (params) => {
+    return (typeof params === "string" ||
+        (typeof params === "object" && params !== null && "name" in params));
+};
+export class AgentCard {
+    _agentCard;
+    constructor(params) {
+        this._agentCard = {
+            protocolVersion: "0.3.0",
+            description: "An agent that can use the A2A protocol.",
+            url: "https://localhost:3000/a2a",
+            version: "0.0.0",
+            capabilities: {},
+            defaultInputModes: [],
+            defaultOutputModes: [],
+            skills: [],
+            preferredTransport: "JSONRPC",
+            ...params,
+        };
+    }
+    get agentCard() {
+        return this._agentCard;
+    }
+    static create(params) {
+        return new AgentCard(typeof params === "string" ? { name: params } : params)
+            .agentCard;
+    }
+}
+/**
+ * @deprecated Use {@link card} instead
+ * @since 0.6.0
+ */
+export const AgentCardBuilder = AgentCard;
+/**
+ * Convenience factory function for creating an {@link A2A.AgentCard} with default parameters.
+ *
+ * @returns New {@link A2A.AgentCard} with default parameters
+ * @defaults {
+ *   description: "An agent that can use the A2A protocol.",
+ *   url: "https://localhost:3000/a2a",
+ *   version: "0.0.0",
+ *   capabilities: {},
+ *   defaultInputModes: [],
+ *   defaultOutputModes: [],
+ *   skills: [],
+ *   preferredTransport: "JSONRPC",
+ * }
+ *
+ * @example
+ * ```typescript
+ * const agentCard = card("My Agent");
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export const card = AgentCard.create;
+/**
+ * @deprecated Use {@link card} instead
+ * @since 0.6.0
+ */
+export const createAgentCard = AgentCard.create;

package/dist/create/base.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Utility type that omits the `kind` property from an object type.
+ */
+export type Kindless<T extends object> = Omit<T, "kind">;

package/dist/create/base.js

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