agentstack-sdk 0.6.1 → 0.6.2-rc2

package/src/experimental/server/core/server/executor.ts

@@ -0,0 +1,284 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Message, Task } from '@a2a-js/sdk';
+import type { AgentExecutor, ExecutionEventBus, RequestContext } from '@a2a-js/sdk/server';
+
+import {
+  createArtifactUpdateEvent,
+  createDataPart,
+  createMessage,
+  createStatusUpdateEvent,
+  createTextPart,
+} from '../../a2a/helpers';
+import { isArtifact, isAsyncIterable, isMessage, isPart, isTaskStatus, isTaskStatusUpdateEvent } from '../../a2a/utils';
+import { RunContext } from '../context';
+import type { ExtensionConfig, ExtensionServer } from '../extensions/types';
+import type { AgentFunction, RunYield } from './types';
+
+export class AgentExecutorImpl<TDeps> implements AgentExecutor {
+  private readonly handler: AgentFunction<TDeps>;
+  private readonly extensions?: ExtensionConfig<TDeps>;
+  private readonly runningTasks: Map<string, { cancelled: boolean }> = new Map();
+
+  constructor(handler: AgentFunction<TDeps>, extensions?: ExtensionConfig<TDeps>) {
+    this.handler = handler;
+    this.extensions = extensions;
+  }
+
+  private getOrCreateTask(requestContext: RequestContext, eventBus: ExecutionEventBus): Task {
+    const { taskId, contextId, task } = requestContext;
+
+    if (task) {
+      return task;
+    }
+
+    const initialTask: Task = {
+      kind: 'task',
+      id: taskId,
+      contextId,
+      status: {
+        state: 'submitted',
+        timestamp: new Date().toISOString(),
+      },
+      history: [],
+    };
+
+    eventBus.publish(initialTask);
+
+    eventBus.publish(
+      createStatusUpdateEvent({
+        taskId: initialTask.id,
+        contextId,
+        status: {
+          state: 'working',
+        },
+        final: false,
+      }),
+    );
+
+    return initialTask;
+  }
+
+  async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
+    const { userMessage, contextId } = requestContext;
+
+    const task = this.getOrCreateTask(requestContext, eventBus);
+    const runContext = new RunContext(task.id, contextId, task);
+    const taskState = { cancelled: false };
+
+    this.runningTasks.set(task.id, taskState);
+
+    try {
+      const deps = this.resolveExtensions(userMessage);
+      const result = this.handler(userMessage, runContext, deps);
+
+      if (isAsyncIterable(result)) {
+        for await (const yielded of result) {
+          if (taskState.cancelled) {
+            this.publishCancelled(eventBus, task.id, contextId);
+
+            return;
+          }
+
+          this.processYield(eventBus, task.id, contextId, yielded);
+        }
+      } else {
+        const awaited = await result;
+
+        if (awaited !== undefined) {
+          this.processYield(eventBus, task.id, contextId, awaited);
+        }
+      }
+
+      if (!taskState.cancelled) {
+        eventBus.publish(
+          createStatusUpdateEvent({
+            taskId: task.id,
+            contextId,
+            status: {
+              state: 'completed',
+            },
+            final: true,
+          }),
+        );
+      }
+    } catch (error) {
+      const message = createMessage({
+        taskId: task.id,
+        contextId,
+        parts: [createTextPart(error instanceof Error ? error.message : 'Unknown error')],
+      });
+
+      eventBus.publish(
+        createStatusUpdateEvent({
+          taskId: task.id,
+          contextId,
+          status: {
+            state: 'failed',
+            message,
+          },
+          final: true,
+        }),
+      );
+
+      this.runningTasks.delete(task.id);
+    } finally {
+      eventBus.finished();
+    }
+  }
+
+  async cancelTask(taskId: string): Promise<void> {
+    const taskState = this.runningTasks.get(taskId);
+
+    if (taskState) {
+      taskState.cancelled = true;
+    }
+  }
+
+  private resolveExtensions(message: Message): TDeps {
+    if (!this.extensions) {
+      return {} as TDeps;
+    }
+
+    const deps: Record<string, unknown> = {};
+
+    for (const [key, ext] of Object.entries(this.extensions) as [string, ExtensionServer][]) {
+      const fulfillments = ext.spec.parseFulfillments(message);
+
+      deps[key] = ext.resolveDeps(fulfillments);
+    }
+
+    return deps as TDeps;
+  }
+
+  private publishCancelled(eventBus: ExecutionEventBus, taskId: string, contextId: string): void {
+    eventBus.publish(
+      createStatusUpdateEvent({
+        taskId,
+        contextId,
+        status: {
+          state: 'canceled',
+        },
+        final: true,
+      }),
+    );
+  }
+
+  private processYield(eventBus: ExecutionEventBus, taskId: string, contextId: string, yielded: RunYield): void {
+    if (typeof yielded === 'string') {
+      const message = createMessage({
+        taskId,
+        contextId,
+        parts: [createTextPart(yielded)],
+      });
+
+      eventBus.publish(
+        createStatusUpdateEvent({
+          taskId,
+          contextId,
+          status: {
+            state: 'working',
+            message,
+          },
+          final: false,
+        }),
+      );
+    } else if (yielded instanceof Error) {
+      const message = createMessage({
+        taskId,
+        contextId,
+        parts: [createTextPart(yielded.message)],
+      });
+
+      eventBus.publish(
+        createStatusUpdateEvent({
+          taskId,
+          contextId,
+          status: {
+            state: 'failed',
+            message,
+          },
+          final: true,
+        }),
+      );
+    } else if (isMessage(yielded)) {
+      const message: Message = {
+        ...yielded,
+        taskId,
+        contextId,
+      };
+
+      eventBus.publish(
+        createStatusUpdateEvent({
+          taskId,
+          contextId,
+          status: {
+            state: 'working',
+            message,
+          },
+          final: false,
+        }),
+      );
+    } else if (isPart(yielded)) {
+      const message = createMessage({
+        taskId,
+        contextId,
+        parts: [yielded],
+      });
+
+      eventBus.publish(
+        createStatusUpdateEvent({
+          taskId,
+          contextId,
+          status: {
+            state: 'working',
+            message,
+          },
+          final: false,
+        }),
+      );
+    } else if (isTaskStatusUpdateEvent(yielded)) {
+      eventBus.publish(yielded);
+    } else if (isTaskStatus(yielded)) {
+      eventBus.publish(
+        createStatusUpdateEvent({
+          taskId,
+          contextId,
+          status: yielded,
+          final: false,
+        }),
+      );
+    } else if (isArtifact(yielded)) {
+      eventBus.publish(
+        createArtifactUpdateEvent({
+          taskId,
+          contextId,
+          artifact: yielded,
+          lastChunk: true,
+          append: false,
+        }),
+      );
+    } else if (typeof yielded === 'object' && yielded != null) {
+      const message = createMessage({
+        taskId,
+        contextId,
+        parts: [createDataPart(yielded)],
+      });
+
+      eventBus.publish(
+        createStatusUpdateEvent({
+          taskId,
+          contextId,
+          status: {
+            state: 'working',
+            message,
+          },
+          final: false,
+        }),
+      );
+    }
+  }
+}

package/src/experimental/server/core/server/helpers.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export function createAgentCardUrl(host: string, port: number, selfRegistrationId?: string) {
+  return `http://${host === '0.0.0.0' ? 'localhost' : host}:${port}${selfRegistrationId ? `#${selfRegistrationId}` : ''}`;
+}
+
+export function normalizeDockerHost(host: string) {
+  return host.replace(/0\.0\.0\.0|localhost|127\.0\.0\.1/g, 'host.docker.internal');
+}

package/src/experimental/server/core/server/index.ts

@@ -0,0 +1,166 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { AgentCard, AgentExtension } from '@a2a-js/sdk';
+import { DefaultRequestHandler, InMemoryTaskStore } from '@a2a-js/sdk/server';
+import { agentCardHandler, jsonRpcHandler, UserBuilder } from '@a2a-js/sdk/server/express';
+import express from 'express';
+
+import { buildApiClient } from '../../../../api';
+import { AgentDetailExtensionSpec } from '../../a2a/extensions/agent-detail';
+import { PlatformSelfRegistrationExtensionSpec } from '../../a2a/extensions/platform-self-registration';
+import { loadConfig } from '../config';
+import type { ExtensionConfig, ExtensionServer } from '../extensions/types';
+import { createAutoregisterToAgentstack } from './autoregistration';
+import { AgentExecutorImpl } from './executor';
+import { createAgentCardUrl } from './helpers';
+import type { AgentOptions, ServerHandle, ServerOptions } from './types';
+
+export class Server {
+  private agentCard?: AgentCard;
+  private agentOptions?: AgentOptions<unknown>;
+  private agentConfigured = false;
+
+  agent<TDeps>(options: AgentOptions<TDeps>): this {
+    if (this.agentConfigured) {
+      throw new Error('Agent already configured. Only one agent per server is supported.');
+    }
+
+    let extensions = this.buildExtensions(options.extensions);
+
+    if (options.detail) {
+      const detailExt = new AgentDetailExtensionSpec(options.detail);
+
+      extensions = [...(extensions ?? []), detailExt.toAgentCardExtension()];
+    }
+
+    this.agentCard = {
+      name: options.name,
+      description: options.description ?? '',
+      url: 'http://localhost:8000',
+      version: options.version ?? '1.0.0',
+      protocolVersion: options.protocolVersion ?? '0.3.0',
+      capabilities: {
+        streaming: true,
+        extensions,
+      },
+      defaultInputModes: ['text'],
+      defaultOutputModes: ['text'],
+      skills: [],
+    };
+
+    this.agentOptions = options as AgentOptions<unknown>;
+    this.agentConfigured = true;
+
+    return this;
+  }
+
+  async run(options: ServerOptions = {}): Promise<ServerHandle> {
+    if (!this.agentConfigured || !this.agentCard || !this.agentOptions) {
+      throw new Error('No agent configured. Call agent() before run().');
+    }
+
+    const config = loadConfig();
+    const host = options.host ?? '0.0.0.0';
+    const port = options.port ?? 8000;
+    const selfRegistrationId = options.selfRegistrationId;
+    const platformUrl = options.platformUrl ?? config.platformUrl;
+    const productionMode = config.productionMode;
+
+    this.agentCard.url = createAgentCardUrl(host, port);
+
+    if (selfRegistrationId && !productionMode) {
+      const selfRegExtension = new PlatformSelfRegistrationExtensionSpec({ self_registration_id: selfRegistrationId });
+
+      this.agentCard.capabilities.extensions = [
+        ...(this.agentCard.capabilities.extensions ?? []),
+        selfRegExtension.toAgentCardExtension(),
+      ];
+    }
+
+    const taskStore = new InMemoryTaskStore();
+    const executor = new AgentExecutorImpl(this.agentOptions.handler, this.agentOptions.extensions);
+    const requestHandler = new DefaultRequestHandler(this.agentCard, taskStore, executor);
+
+    const app = express();
+
+    const agentCardPath = `/.well-known/agent-card.json`;
+
+    app.use(jsonRpcHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
+    app.use(agentCardPath, agentCardHandler({ agentCardProvider: requestHandler }));
+
+    const api = buildApiClient({ baseUrl: platformUrl });
+
+    let stopAutoregistration: (() => void) | undefined;
+
+    if (selfRegistrationId && !productionMode) {
+      stopAutoregistration = createAutoregisterToAgentstack({
+        selfRegistrationId,
+        agentCard: this.agentCard,
+        host,
+        port,
+        api,
+      });
+    }
+
+    return new Promise((resolve, reject) => {
+      const server = app.listen(port, host, async () => {
+        console.log(`Agent "${this.agentCard!.name}" running at http://${host}:${port}`);
+        console.log(`Agent card available at http://${host}:${port}${agentCardPath}`);
+
+        const url = createAgentCardUrl(host, port);
+        const handle: ServerHandle = {
+          port,
+          url,
+          close: () =>
+            new Promise((resolveClose, rejectClose) => {
+              stopAutoregistration?.();
+
+              server.close((error) => {
+                if (error) {
+                  rejectClose(error);
+                } else {
+                  resolveClose();
+                }
+              });
+            }),
+        };
+
+        resolve(handle);
+      });
+
+      server.on('error', (error) => {
+        stopAutoregistration?.();
+        reject(error);
+      });
+
+      const cleanup = () => {
+        stopAutoregistration?.();
+        server.close();
+      };
+
+      process.on('SIGTERM', cleanup);
+      process.on('SIGINT', cleanup);
+    });
+  }
+
+  private buildExtensions(extensionConfig: ExtensionConfig | undefined): AgentExtension[] | undefined {
+    if (!extensionConfig) {
+      return undefined;
+    }
+
+    const extensions: AgentExtension[] = [];
+
+    for (const ext of Object.values(extensionConfig) as ExtensionServer[]) {
+      extensions.push(ext.spec.toAgentCardExtension());
+    }
+
+    if (extensions.length === 0) {
+      return undefined;
+    }
+
+    return extensions;
+  }
+}

package/src/experimental/server/core/server/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { AgentCard, Artifact, Message, Part, TaskStatus, TaskStatusUpdateEvent } from '@a2a-js/sdk';
+
+import type { buildApiClient } from '../../../../api';
+import type { AgentDetail } from '../../../../client/a2a/extensions/ui/agent-detail/types';
+import type { RunContext } from '../context';
+import type { ExtensionConfig } from '../extensions/types';
+
+export type RunYield =
+  | string
+  | Message
+  | Part
+  | TaskStatus
+  | TaskStatusUpdateEvent
+  | Artifact
+  | Error
+  | Record<string, unknown>;
+
+export type AgentFunction<TDeps = Record<string, never>> = (
+  input: Message,
+  ctx: RunContext,
+  deps: TDeps,
+) => AsyncIterable<RunYield> | Promise<RunYield | void>;
+
+export interface AgentOptions<TDeps = Record<string, never>> {
+  name: string;
+  description?: string;
+  detail?: AgentDetail;
+  extensions?: ExtensionConfig<TDeps>;
+  version?: string;
+  protocolVersion?: string;
+  handler: AgentFunction<TDeps>;
+}
+
+export interface ServerOptions {
+  host?: string;
+  port?: number;
+  selfRegistrationId?: string;
+  platformUrl?: string;
+}
+
+export interface ServerHandle {
+  port: number;
+  url: string;
+  close: () => Promise<void>;
+}
+
+export interface AutoregistrationOptions {
+  selfRegistrationId: string;
+  agentCard: AgentCard;
+  host: string;
+  port: number;
+  api: ReturnType<typeof buildApiClient>;
+}

package/src/experimental/server/core/types.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from './config/types';
+export * from './extensions/types';
+export * from './server/types';

package/src/experimental/server/core/utils.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+interface RetryOptions {
+  maxAttempts?: number;
+  maxDelayMs?: number;
+  shouldAbort?: () => boolean;
+  onRetry?: (attempt: number, error: Error, delayMs: number) => void;
+}
+
+export async function withRetry<T>(fn: () => Promise<T>, options: RetryOptions = {}): Promise<T> {
+  const { maxAttempts = 10, maxDelayMs = 10000, shouldAbort, onRetry } = options;
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (shouldAbort?.()) {
+      throw new Error('Operation aborted');
+    }
+
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      const delay = Math.min(1000 * Math.pow(2, attempt), maxDelayMs);
+
+      onRetry?.(attempt + 1, lastError, delay);
+
+      await sleep(delay);
+    }
+  }
+
+  throw lastError ?? new Error('Max retry attempts exceeded');
+}
+
+export function setsEqual(a: Set<string>, b: Set<string>): boolean {
+  if (a.size !== b.size) {
+    return false;
+  }
+
+  for (const item of a) {
+    if (!b.has(item)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export function getErrorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}

package/{dist/client/api/core/errors/index.d.ts → src/server.ts}

@@ -2,5 +2,6 @@
  * Copyright 2025 © BeeAI a Series of LF Projects, LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-export * from './types';
-export * from './utils';
+
+export * from './experimental/server/a2a';
+export * from './experimental/server/core';