agentstack-sdk 0.6.1 → 0.6.2-rc2

package/src/experimental/server/a2a/extensions/llm/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Message } from '@a2a-js/sdk';
+
+import { LLM_EXTENSION_URI, llmFulfillmentsSchema } from '../../../../../extensions';
+import type { ExtensionServer, ExtensionSpec } from '../../../core/extensions/types';
+import type { LLMExtensionDeps, LLMExtensionFulfillments, LLMExtensionParams } from './types';
+
+export class LLMExtensionSpec implements ExtensionSpec<LLMExtensionParams, LLMExtensionFulfillments> {
+  readonly uri = LLM_EXTENSION_URI;
+  readonly params: LLMExtensionParams;
+  readonly fulfillmentsSchema = llmFulfillmentsSchema;
+
+  constructor(params: LLMExtensionParams) {
+    this.params = params;
+  }
+
+  toAgentCardExtension() {
+    return {
+      uri: this.uri,
+      required: true,
+      params: {
+        llm_demands: this.params.demands,
+      },
+    };
+  }
+
+  parseFulfillments(message: Message) {
+    const { metadata } = message;
+
+    if (!metadata) {
+      return undefined;
+    }
+
+    const extensionData = metadata[this.uri];
+
+    if (!extensionData) {
+      return undefined;
+    }
+
+    const { success, data } = this.fulfillmentsSchema.safeParse(extensionData);
+
+    if (!success) {
+      return undefined;
+    }
+
+    return data;
+  }
+}
+
+export class LLMExtensionServer implements ExtensionServer<
+  LLMExtensionDeps,
+  LLMExtensionParams,
+  LLMExtensionFulfillments
+> {
+  readonly spec: LLMExtensionSpec;
+
+  constructor(params: LLMExtensionParams) {
+    this.spec = new LLMExtensionSpec(params);
+  }
+
+  resolveDeps(fulfillments: LLMExtensionFulfillments | undefined): LLMExtensionDeps {
+    return {
+      fulfillments: fulfillments?.llm_fulfillments,
+    };
+  }
+}

package/src/experimental/server/a2a/extensions/llm/types.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { LLMDemand, LLMFulfillment, LLMFulfillments } from '../../../../../extensions';
+
+export interface LLMExtensionParams {
+  demands: Record<string, LLMDemand>;
+}
+
+export type LLMExtensionFulfillments = LLMFulfillments;
+
+export interface LLMExtensionDeps {
+  fulfillments?: Record<string, LLMFulfillment>;
+}

package/src/experimental/server/a2a/extensions/platform-self-registration/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ExtensionSpec } from '../../../core/extensions/types';
+import type { PlatformSelfRegistrationExtensionFulfillments, PlatformSelfRegistrationExtensionParams } from './types';
+
+export const PLATFORM_SELF_REGISTRATION_EXTENSION_URI =
+  'https://a2a-extensions.agentstack.beeai.dev/services/platform-self-registration/v1';
+
+export class PlatformSelfRegistrationExtensionSpec implements ExtensionSpec<
+  PlatformSelfRegistrationExtensionParams,
+  PlatformSelfRegistrationExtensionFulfillments
+> {
+  readonly uri = PLATFORM_SELF_REGISTRATION_EXTENSION_URI;
+  readonly params: PlatformSelfRegistrationExtensionParams;
+
+  constructor(params: PlatformSelfRegistrationExtensionParams) {
+    this.params = params;
+  }
+
+  toAgentCardExtension() {
+    return {
+      uri: this.uri,
+      required: false,
+      params: this.params,
+    };
+  }
+
+  parseFulfillments() {
+    return undefined;
+  }
+}

package/src/experimental/server/a2a/extensions/platform-self-registration/types.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface PlatformSelfRegistrationExtensionParams extends Record<string, unknown> {
+  self_registration_id: string;
+}
+
+export type PlatformSelfRegistrationExtensionFulfillments = undefined;

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

@@ -0,0 +1,95 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  Artifact,
+  DataPart,
+  Message,
+  Part,
+  TaskArtifactUpdateEvent,
+  TaskStatus,
+  TaskStatusUpdateEvent,
+  TextPart,
+} from '@a2a-js/sdk';
+import { randomUUID } from 'crypto';
+
+export function createMessage({
+  taskId,
+  contextId,
+  parts,
+  metadata,
+}: {
+  taskId: string;
+  contextId: string;
+  parts: Part[];
+  metadata?: Record<string, unknown>;
+}): Message {
+  return {
+    kind: 'message',
+    messageId: randomUUID(),
+    role: 'agent',
+    taskId,
+    contextId,
+    parts,
+    metadata,
+  };
+}
+
+export function createTextPart(text: string): TextPart {
+  return {
+    kind: 'text',
+    text,
+  };
+}
+
+export function createDataPart(data: Record<string, unknown>): DataPart {
+  return {
+    kind: 'data',
+    data,
+  };
+}
+
+export function createStatusUpdateEvent({
+  taskId,
+  contextId,
+  status,
+  final,
+}: {
+  taskId: string;
+  contextId: string;
+  status: TaskStatus;
+  final: boolean;
+}): TaskStatusUpdateEvent {
+  return {
+    kind: 'status-update',
+    taskId,
+    contextId,
+    status,
+    final,
+  };
+}
+
+export function createArtifactUpdateEvent({
+  taskId,
+  contextId,
+  artifact,
+  lastChunk,
+  append,
+}: {
+  taskId: string;
+  contextId: string;
+  artifact: Artifact;
+  lastChunk: boolean;
+  append: boolean;
+}): TaskArtifactUpdateEvent {
+  return {
+    kind: 'artifact-update',
+    taskId,
+    contextId,
+    artifact,
+    lastChunk,
+    append,
+  };
+}

package/{dist/client/a2a/index.d.ts → src/experimental/server/a2a/index.ts}

@@ -2,5 +2,5 @@
  * Copyright 2025 © BeeAI a Series of LF Projects, LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+
 export * from './extensions';
-export * from './protocol';

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

@@ -0,0 +1,43 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Artifact, Message, Part, TaskStatus, TaskStatusUpdateEvent, TextPart } from '@a2a-js/sdk';
+
+function isObjectLike(value: unknown) {
+  return value != null && typeof value === 'object';
+}
+
+export function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T> {
+  return isObjectLike(value) && Symbol.asyncIterator in value;
+}
+
+export function isMessage(value: unknown): value is Message {
+  return isObjectLike(value) && 'kind' in value && value.kind === 'message';
+}
+
+export function isArtifact(value: unknown): value is Artifact {
+  return isObjectLike(value) && 'artifactId' in value;
+}
+
+export function isPart(value: unknown): value is Part {
+  return (
+    isObjectLike(value) &&
+    'kind' in value &&
+    typeof value.kind === 'string' &&
+    ['text', 'file', 'data'].includes(value.kind)
+  );
+}
+
+export function isTextPart(part: Part | undefined): part is TextPart {
+  return part != null && part.kind === 'text';
+}
+
+export function isTaskStatus(value: unknown): value is TaskStatus {
+  return isObjectLike(value) && 'state' in value;
+}
+
+export function isTaskStatusUpdateEvent(value: unknown): value is TaskStatusUpdateEvent {
+  return isObjectLike(value) && 'kind' in value && value.kind === 'status-update';
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { configSchema } from './schemas';
+
+export function loadConfig() {
+  return configSchema.parse({
+    platformUrl: process.env.PLATFORM_URL,
+    productionMode: process.env.PRODUCTION_MODE,
+  });
+}
+
+export function isProductionMode() {
+  return loadConfig().productionMode;
+}

package/src/experimental/server/core/config/schemas.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+export const configSchema = z.object({
+  platformUrl: z.string().default('http://127.0.0.1:8333'),
+  productionMode: z
+    .string()
+    .optional()
+    .transform((value) => value?.toLowerCase() === 'true' || value === '1')
+    .default(false),
+});

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

@@ -0,0 +1,10 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type z from 'zod';
+
+import type { configSchema } from './schemas';
+
+export type Config = z.infer<typeof configSchema>;

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

@@ -0,0 +1,18 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Task } from '@a2a-js/sdk';
+
+export class RunContext {
+  readonly taskId: string;
+  readonly contextId: string;
+  readonly task?: Task;
+
+  constructor(taskId: string, contextId: string, task?: Task) {
+    this.taskId = taskId;
+    this.contextId = contextId;
+    this.task = task;
+  }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { AgentExtension, Message } from '@a2a-js/sdk';
+import type { z } from 'zod';
+
+export interface ExtensionSpec<TParams = unknown, TFulfillments = unknown> {
+  uri: string;
+  params?: TParams;
+  fulfillmentsSchema?: z.ZodSchema<TFulfillments>;
+  toAgentCardExtension(): AgentExtension;
+  parseFulfillments(message: Message): TFulfillments | undefined;
+}
+
+export interface ExtensionServer<TDeps = unknown, TParams = unknown, TFulfillments = unknown> {
+  spec: ExtensionSpec<TParams, TFulfillments>;
+  resolveDeps(fulfillments: TFulfillments | undefined): TDeps;
+}
+
+export type ExtensionConfig<TDeps = unknown> = {
+  [K in keyof TDeps]: ExtensionServer<TDeps[K], unknown, unknown>;
+};

package/{dist/client/a2a/protocol/index.d.ts → src/experimental/server/core/index.ts}

@@ -2,5 +2,9 @@
  * Copyright 2025 © BeeAI a Series of LF Projects, LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+
+export * from './config';
+export * from './context';
 export * from './schemas';
+export * from './server';
 export * from './types';

package/{dist/client/a2a/protocol/tests.d.ts → src/experimental/server/core/schemas.ts}

@@ -2,4 +2,5 @@
  * Copyright 2025 © BeeAI a Series of LF Projects, LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-export {};
+
+export * from './config/schemas';

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

@@ -0,0 +1,142 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ApiErrorType } from '../../../../api';
+import { isProductionMode } from '../config';
+import { getErrorMessage, setsEqual, withRetry } from '../utils';
+import { createAgentCardUrl, normalizeDockerHost } from './helpers';
+import type { AutoregistrationOptions } from './types';
+
+const VARIABLE_RELOAD_INTERVAL_MS = 5000;
+
+export function createAutoregisterToAgentstack(options: AutoregistrationOptions): () => void {
+  const { selfRegistrationId, agentCard, host, port, api } = options;
+
+  let providerId: string | null = null;
+  let variableReloadInterval: ReturnType<typeof setInterval> | null = null;
+  let configuredVariables = new Set<string>();
+  let stopped = false;
+
+  async function loadVariables(firstRun = false): Promise<void> {
+    if (!providerId) {
+      return;
+    }
+
+    try {
+      const result = await api.listProviderVariables({ id: providerId });
+
+      if (!result.ok) {
+        console.warn(`Failed to load variables: ${result.error.message}`);
+
+        return;
+      }
+
+      const variables = result.data.variables;
+      const oldVariables = configuredVariables;
+      const newVariables = new Set<string>();
+
+      for (const variable of configuredVariables) {
+        if (!(variable in variables)) {
+          delete process.env[variable];
+        }
+      }
+
+      for (const [key, value] of Object.entries(variables)) {
+        process.env[key] = value;
+        newVariables.add(key);
+      }
+
+      const dirty = !setsEqual(oldVariables, newVariables);
+      configuredVariables = newVariables;
+
+      if (dirty && configuredVariables.size > 0) {
+        console.log(`Environment variables reloaded: ${[...configuredVariables].join(', ')}`);
+      }
+
+      if (firstRun && configuredVariables.size > 0) {
+        console.log('Environment variables loaded.');
+      }
+    } catch (error) {
+      console.error(`Failed to load variables: ${getErrorMessage(error)}`);
+    }
+  }
+
+  async function register(): Promise<void> {
+    if (isProductionMode()) {
+      console.log('Agent is not automatically registered in production mode.');
+
+      return;
+    }
+
+    const location = createAgentCardUrl(normalizeDockerHost(host), port, selfRegistrationId);
+
+    console.log('Registering agent to the Agent Stack platform', { location });
+
+    try {
+      await withRetry(
+        async () => {
+          const existingResult = await api.readProviderByLocation({
+            location: encodeURIComponent(location),
+          });
+
+          if (existingResult.ok) {
+            const patchResult = await api.patchProvider({
+              id: existingResult.data.id,
+              agent_card: agentCard,
+            });
+
+            if (!patchResult.ok) {
+              throw new Error(`Failed to patch provider: ${patchResult.error.message}`);
+            }
+
+            providerId = patchResult.data.id;
+          } else if (existingResult.error.type === ApiErrorType.Http && existingResult.error.response.status === 404) {
+            const createResult = await api.createProvider({
+              location,
+              agent_card: agentCard,
+            });
+
+            if (!createResult.ok) {
+              throw new Error(`Failed to create provider: ${createResult.error.message}`);
+            }
+
+            providerId = createResult.data.id;
+          } else {
+            throw new Error(`Failed to lookup provider: ${existingResult.error.message}`);
+          }
+        },
+        {
+          shouldAbort: () => stopped,
+          onRetry: (attempt, _error, delayMs) => {
+            console.warn(`Registration attempt ${attempt} failed, retrying in ${delayMs}ms...`);
+          },
+        },
+      );
+
+      console.log('Agent registered successfully');
+
+      await loadVariables(true);
+
+      variableReloadInterval = setInterval(() => {
+        loadVariables().catch((error) => console.error('Error during variable reload:', error));
+      }, VARIABLE_RELOAD_INTERVAL_MS);
+    } catch (error) {
+      console.error(`Agent cannot be registered to agentstack server: ${getErrorMessage(error)}`);
+    }
+  }
+
+  function stop(): void {
+    stopped = true;
+
+    if (variableReloadInterval) {
+      clearInterval(variableReloadInterval);
+      variableReloadInterval = null;
+    }
+  }
+
+  register();
+
+  return stop;
+}