@artinet/sdk 0.5.18 → 0.6.0-preview.2

package/dist/create/task-builder.js

@@ -0,0 +1,384 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+import { v4 as uuidv4 } from "uuid";
+import { getCurrentTimestamp } from "../utils/common/utils.js";
+import { isMessageParams, Message,
+// type BuilderMessageParams,
+ } from "./message-builder.js";
+export const isArtifactParams = (params) => {
+    return (typeof params === "string" ||
+        (typeof params === "object" && params !== null && "parts" in params));
+};
+export class Artifact {
+    _artifact;
+    constructor(artifact_params = {}) {
+        this._artifact = {
+            artifactId: uuidv4(),
+            parts: [],
+            ...artifact_params,
+        };
+    }
+    get artifact() {
+        return this._artifact;
+    }
+    static create(params = {}) {
+        return new Artifact(typeof params === "string"
+            ? { parts: [{ text: params, kind: "text" }] }
+            : params).artifact;
+    }
+}
+export const artifact = Artifact.create;
+export const isStatusParams = (params) => {
+    return (typeof params === "string" ||
+        (typeof params === "object" &&
+            params !== null &&
+            "state" in params &&
+            params.state in A2A.TaskState) ||
+        (typeof params === "object" &&
+            params !== null &&
+            "message" in params &&
+            isMessageParams(params.message)));
+};
+export class TaskStatus {
+    _status;
+    constructor(params = {}) {
+        const timestamp = params.timestamp ?? getCurrentTimestamp();
+        this._status = {
+            ...params,
+            state: params.state ?? A2A.TaskState.working,
+            timestamp,
+        };
+    }
+    get status() {
+        return this._status;
+    }
+    static create(params = {}) {
+        if (typeof params === "string" && params in A2A.TaskState) {
+            return new TaskStatus({ state: params }).status;
+        }
+        else if (isMessageParams(params)) {
+            return new TaskStatus({
+                state: A2A.TaskState.working,
+                message: Message.create(params),
+            }).status;
+        }
+        return new TaskStatus(params).status;
+    }
+}
+/**
+ * Convenience factory function for creating a task status with default parameters.
+ *
+ * @returns New {@link A2A.TaskStatus} with default parameters
+ * @defaults {
+ *   state: "working",
+ *   timestamp: getCurrentTimestamp(),
+ * }
+ *
+ * @example
+ * ```typescript
+ * const status = status("working");
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export const status = TaskStatus.create;
+export class Task {
+    _task;
+    constructor(params = {}) {
+        const id = params.id ?? uuidv4();
+        this._task = {
+            ...params,
+            id,
+            contextId: params.contextId ?? id,
+            kind: A2A.Kind.task,
+            status: TaskStatus.create(params.status),
+        };
+    }
+    get task() {
+        return this._task;
+    }
+    static create(params = {}) {
+        if (isStatusParams(params)) {
+            return new Task({ status: TaskStatus.create(params) }).task;
+        }
+        return new Task(params).task;
+    }
+}
+/**
+ * Convenience factory function for creating a task with default parameters.
+ *
+ * @returns New {@link A2A.Task} with default parameters
+ * @defaults:
+ * - `id`: uuidv4()
+ * - `contextId`: id
+ * - `status`: { state: "working" }
+ * @example
+ * ```typescript
+ * const task = task({ status: { state: "working" } });
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export const task = Task.create;
+export class TaskStatusUpdateEvent {
+    _event;
+    constructor(params) {
+        const taskId = params.taskId ?? params.status.message?.taskId ?? uuidv4();
+        const contextId = params.contextId ?? params.status.message?.contextId ?? taskId;
+        this._event = {
+            ...params,
+            taskId,
+            contextId,
+            kind: A2A.Kind["status-update"],
+            final: params.final ?? false,
+        };
+    }
+    get event() {
+        return this._event;
+    }
+    static create(params) {
+        if (isStatusParams(params)) {
+            return new TaskStatusUpdateEvent({
+                /*allows for a mixture of Update & Status Params*/
+                ...(typeof params === "object" ? params : {}),
+                status: TaskStatus.create(params),
+            }).event;
+        }
+        return new TaskStatusUpdateEvent(params).event;
+    }
+}
+export class TaskArtifactUpdateEvent {
+    _event;
+    constructor(params) {
+        const taskId = params.taskId ?? uuidv4();
+        this._event = {
+            ...params,
+            taskId,
+            contextId: params.contextId ?? taskId,
+            kind: A2A.Kind["artifact-update"],
+        };
+    }
+    get event() {
+        return this._event;
+    }
+    static create(params) {
+        if (isArtifactParams(params)) {
+            return new TaskArtifactUpdateEvent({
+                artifact: Artifact.create(params),
+            }).event;
+        }
+        return new TaskArtifactUpdateEvent({
+            ...params,
+            artifact: Artifact.create(params.artifact),
+        }).event;
+    }
+}
+const strict_update = (params) => {
+    return TaskStatusUpdateEvent.create(params);
+};
+function _buildUpdate(state, params, final) {
+    return strict_update({
+        taskId: params.taskId,
+        contextId: params.contextId,
+        status: {
+            state: state,
+            message: params.message,
+            timestamp: params.timestamp,
+        },
+        final: final ?? params.final,
+        metadata: params.metadata,
+    });
+}
+function _working(params) {
+    return _buildUpdate(A2A.TaskState.working, params);
+}
+function _canceled(params) {
+    return _buildUpdate(A2A.TaskState.canceled, params, true);
+}
+function _submitted(params) {
+    return _buildUpdate(A2A.TaskState.submitted, params);
+}
+function _failed(params) {
+    return _buildUpdate(A2A.TaskState.failed, params, true);
+}
+function _completed(params) {
+    return _buildUpdate(A2A.TaskState.completed, params, true);
+}
+function _inputRequired(params) {
+    return _buildUpdate(A2A.TaskState["input-required"], params);
+}
+function _rejected(params) {
+    return _buildUpdate(A2A.TaskState.rejected, params);
+}
+function _authRequired(params) {
+    return _buildUpdate(A2A.TaskState["auth-required"], params);
+}
+function _unknown(params) {
+    return _buildUpdate(A2A.TaskState["unknown"], params);
+}
+/**
+ * Convenience factory function for creating a task status and artifact update events with default parameters.
+ *
+ * @returns New {@link A2A.TaskStatusUpdateEvent} and {@link A2A.TaskArtifactUpdateEvent} with default parameters
+ *
+ * @example
+ * ```typescript
+ * const artifactEvent = update.artifact({
+ *   artifact: "result"
+ * });
+ * const statusEvent = update.status({
+ *   status: "working"
+ * });
+ * ```
+ *
+ * @public
+ * @since 0.6.0
+ */
+export const update = {
+    /**
+     * Convenience factory function for creating a task artifact update event.
+     * @returns New {@link A2A.TaskArtifactUpdateEvent}
+     * @example
+     * ```typescript
+     * const event = update.artifact({
+     *   artifact: "result"
+     * });
+     * ```
+     */
+    artifact: TaskArtifactUpdateEvent.create,
+    /**
+     * Convenience factory function for creating a task status update event.
+     * @returns New {@link A2A.TaskStatusUpdateEvent}
+     * @example
+     * ```typescript
+     * const event = update.status({
+     *   message: "Working on the task"
+     * });
+     * ```
+     */
+    status: TaskStatusUpdateEvent.create,
+    /**
+     * Convenience factory function for creating a task status update event with the working state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.working} state
+     * @example
+     * ```typescript
+     * const event = update.working({
+     *   message: "Working on the task"
+     * });
+     * ```
+     */
+    working: _working,
+    /**
+     * Convenience factory function for creating a task status update event with the canceled state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.canceled} state
+     * @example
+     * ```typescript
+     * const event = update.canceled({
+     *   message: "Task canceled"
+     * });
+     * ```
+     */
+    canceled: _canceled,
+    /**
+     * Convenience factory function for creating a task status update event with the submitted state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.submitted} state
+     * @example
+     * ```typescript
+     * const event = update.submitted({
+     *   message: "Task submitted"
+     * });
+     * ```
+     */
+    submitted: _submitted,
+    /**
+     * Convenience factory function for creating a task status update event with the failed state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.failed} state
+     * @example
+     * ```typescript
+     * const event = update.failed({
+     *   message: "Task failed"
+     * });
+     * ```
+     */
+    failed: _failed,
+    /**
+     * Convenience factory function for creating a task status update event with the completed state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.completed} state
+     * @example
+     * ```typescript
+     * const event = update.completed({
+     *   message: "Task completed"
+     * });
+     * ```
+     */
+    completed: _completed,
+    /**
+     * Convenience factory function for creating a task status update event with the input required state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState["input-required"]} state
+     * @example
+     * ```typescript
+     * const event = update.inputRequired({
+     *   message: "Task input required"
+     * });
+     * ```
+     */
+    inputRequired: _inputRequired,
+    /**
+     * Convenience factory function for creating a task status update event with the rejected state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.rejected} state
+     * @example
+     * ```typescript
+     * const event = update.rejected({
+     *   message: "Task rejected"
+     * });
+     * ```
+     */
+    rejected: _rejected,
+    /**
+     * Convenience factory function for creating a task status update event with the auth required state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState["auth-required"]} state
+     * @example
+     * ```typescript
+     * const event = update.authRequired({
+     *   message: {
+     *   role: "agent"
+     *   parts: [
+     *     {
+     *       text: "Task auth required"
+     *     }
+     *   ]
+     *   kind: "message"
+     * });
+     * ```
+     */
+    authRequired: _authRequired,
+    /**
+     * Convenience factory function for creating a task status update event with the unknown state.
+     * @returns New {@link A2A.TaskStatusUpdateEvent} with the {@link A2A.TaskState.unknown} state
+     * @example
+     * ```typescript
+     * const event = update.unknown({
+     *   message: "Task unknown"
+     * });
+     * ```
+     */
+    unknown: _unknown,
+};
+/**
+ * @description A temporary compatibility function for updating a task status, purely for migration purposes.
+ * @deprecated Use {@link update.status} instead
+ * @since 0.6.0
+ */
+export const update_compat = (taskId, contextId, state, message, timestamp, final = false) => {
+    return _buildUpdate(state, {
+        taskId: taskId,
+        contextId: contextId,
+        message: message,
+        timestamp: timestamp,
+    }, final);
+};

package/dist/create/transform.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+import * as Builder from "./agent-builder.js";
+import { MessageParams } from "./message-builder.js";
+import { StatusUpdateParams, ArtifactUpdateParams, TaskParams } from "./task-builder.js";
+export declare function hasCarry<Ret extends Builder.AcceptedReturnValues, Carried extends Builder.BaseArgs>(ret: Builder.Reply<Ret, Carried>): ret is Builder.ReturnAndCarry<Ret, Carried>;
+export declare function hasReply<Ret extends Builder.AcceptedReturnValues, Carried extends Builder.BaseArgs>(ret: Builder.Reply<Ret, Carried>): ret is Builder.ReturnValue<Ret>;
+export declare function Parts(kind: "text" | "file" | "data"): Builder.Transform<Builder.AcceptedParts>;
+export declare function Message(): Builder.Transform<Builder.Stateless<MessageParams>>;
+export declare function Artifact(): Builder.Transform<Builder.Stateless<ArtifactUpdateParams>>;
+export declare function Status(): Builder.Transform<Builder.Stateless<StatusUpdateParams>>;
+export declare function Task(): Builder.Transform<Builder.Stateless<TaskParams>>;
+export declare function Reply<Ret extends Builder.AcceptedReturnValues, Carried extends Builder.BaseArgs>(ret: Builder.Reply<Ret, Carried>, context: A2A.Context, transform: Builder.Transform<Ret>): AsyncGenerator<A2A.Update, Carried | undefined, unknown>;

package/dist/create/transform.js

@@ -0,0 +1,106 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe } from "./index.js";
+import { TaskStatus, } from "./task-builder.js";
+export function hasCarry(ret) {
+    return (ret !== null && typeof ret === "object" && "reply" in ret && "args" in ret);
+}
+export function hasReply(ret) {
+    return ret !== null && typeof ret === "object" && "reply" in ret;
+}
+function messagePart(params) {
+    switch (params.kind) {
+        case "text": {
+            return describe.part.text(params.part);
+        }
+        case "file": {
+            return describe.part.file(params.part);
+        }
+        case "data": {
+            return describe.part.data(params.part);
+        }
+        default:
+            throw new Error("Invalid part detected", { cause: params });
+    }
+}
+export function Parts(kind) {
+    return async function* (payload, { taskId, contextId }) {
+        const parts = (Array.isArray(payload) ? payload : [payload]).map((part) => messagePart({ kind, part }));
+        yield describe.update.working({
+            taskId,
+            contextId,
+            message: describe.message({ role: "agent", parts }),
+        });
+        return;
+    };
+}
+export function Message() {
+    return async function* (payload, { taskId, contextId }) {
+        if (Array.isArray(payload)) {
+            throw new Error("Array of messages is not supported");
+        }
+        const message = typeof payload === "string" ? describe.message(payload) : payload;
+        yield describe.message({
+            ...message,
+            taskId,
+            contextId,
+        });
+        return;
+    };
+}
+export function Artifact() {
+    return async function* (payload, { taskId, contextId }) {
+        const updates = Array.isArray(payload) ? payload : [payload];
+        for (const update of updates) {
+            const artifact = typeof update === "string" ? describe.artifact(update) : update;
+            yield describe.update.artifact({
+                ...artifact,
+                taskId,
+                contextId,
+            });
+        }
+        return;
+    };
+}
+export function Status() {
+    return async function* (payload, { taskId, contextId }) {
+        const updates = Array.isArray(payload) ? payload : [payload];
+        for (const update of updates) {
+            const status = typeof update === "string" ? TaskStatus.create(update) : update;
+            yield describe.update.status({
+                ...status,
+                taskId,
+                contextId,
+            });
+        }
+        return;
+    };
+}
+export function Task() {
+    return async function* (payload, { taskId, contextId }) {
+        if (Array.isArray(payload)) {
+            throw new Error("Array of tasks is not supported");
+        }
+        const task = typeof payload === "string" ? describe.task(payload) : payload;
+        yield describe.task({ ...task, taskId, contextId });
+        return;
+    };
+}
+export async function* Reply(ret, context, transform) {
+    if (Array.isArray(ret)) {
+        yield* transform(ret, context);
+    }
+    else if (hasCarry(ret)) {
+        yield* transform(ret.reply, context);
+        return ret.args;
+    }
+    else if (hasReply(ret)) {
+        yield* transform(ret.reply, context);
+    }
+    else {
+        yield* transform(ret, context);
+    }
+    return;
+}

package/dist/extensions/otel.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview OpenTelemetry integration for Artinet SDK.
+ *
+ * Lightweight utilities for integrating user-configured OpenTelemetry
+ * with the SDK's tracing and logging interfaces.
+ *
+ * @module @artinet/sdk/otel
+ *
+ * @example
+ * ```typescript
+ * import { trace } from '@opentelemetry/api';
+ * import { configure } from '@artinet/sdk';
+ * import { configureOtel, withSpan } from '@artinet/sdk/otel';
+ *
+ * // User initializes their own OpenTelemetry setup
+ * // ... NodeSDK setup, exporters, etc. ...
+ *
+ * // Get tracer and configure SDK
+ * const tracer = trace.getTracer('my-agent');
+ * configure({
+ *   tracer,
+ *   logger: configureOtel({ level: 'debug' })
+ * });
+ * ```
+ */
+import { trace, context, SpanKind, SpanStatusCode, Tracer, Span, Context } from "@opentelemetry/api";
+import type { ILogger } from "../config/observability.js";
+/**
+ * Options for configuring the OTel-aware logger.
+ */
+export interface OtelLoggerOptions {
+    /**
+     * Base logger to wrap (logs go here AND to spans).
+     * If not provided, logs only go to spans.
+     */
+    baseLogger?: ILogger;
+    /**
+     * Log level.
+     * @default 'info'
+     */
+    level?: "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent";
+}
+/**
+ * Create a logger that adds log events to the current span.
+ *
+ * This logger optionally wraps a base logger and adds all log messages
+ * as span events in the current trace context.
+ *
+ * @param options - Logger options
+ * @returns ILogger implementation
+ *
+ * @example
+ * ```typescript
+ * import { configure } from '@artinet/sdk';
+ * import { configureOtel } from '@artinet/sdk/otel';
+ * import { configurePino } from '@artinet/sdk/pino';
+ * import pino from 'pino';
+ *
+ * // Logs go to both Pino AND span events
+ * configure({
+ *   logger: configureOtel({
+ *     baseLogger: configurePino(pino()),
+ *     level: 'debug'
+ *   })
+ * });
+ * ```
+ */
+export declare function configureOtel(options?: OtelLoggerOptions): ILogger;
+/**
+ * Execute a function within a new span.
+ *
+ * @param tracer - User's tracer instance
+ * @param name - Span name
+ * @param fn - Function to execute
+ * @param options - Optional span options
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * import { trace } from '@opentelemetry/api';
+ * import { withSpan } from '@artinet/sdk/otel';
+ *
+ * const tracer = trace.getTracer('my-agent');
+ * const result = await withSpan(tracer, 'processTask', async (span) => {
+ *   span.setAttribute('taskId', '123');
+ *   return await doWork();
+ * });
+ * ```
+ */
+export declare function withSpan<T>(tracer: Tracer, name: string, fn: (span: Span) => Promise<T>, options?: {
+    kind?: SpanKind;
+    attributes?: Record<string, string | number | boolean>;
+}): Promise<T>;
+/**
+ * Re-export OpenTelemetry API types for convenience.
+ */
+export { trace, context, SpanKind, SpanStatusCode, type Tracer, type Span, type Context, };
+export default configureOtel;