agentstack-sdk 0.4.2-rc1

package/src/client/a2a/extensions/handle-agent-card.ts

@@ -0,0 +1,116 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { AgentCapabilities } from '@a2a-js/sdk';
+
+import type { ContextToken } from '../../api/types';
+import type { EmbeddingDemands, EmbeddingFulfillments } from './services/embedding';
+import { embeddingExtension } from './services/embedding';
+import type { FormDemands, FormFulfillments } from './services/form';
+import { formExtension } from './services/form';
+import type { LLMDemands, LLMFulfillments } from './services/llm';
+import { llmExtension } from './services/llm';
+import type { MCPDemands, MCPFulfillments } from './services/mcp';
+import { mcpExtension } from './services/mcp';
+import type { OAuthDemands, OAuthFulfillments } from './services/oauth-provider';
+import { oauthProviderExtension } from './services/oauth-provider';
+import { platformApiExtension } from './services/platform';
+import type { SecretDemands, SecretFulfillments } from './services/secrets';
+import { secretsExtension } from './services/secrets';
+import { oauthRequestExtension } from './ui/oauth';
+import type { SettingsDemands, SettingsFulfillments } from './ui/settings';
+import { settingsExtension } from './ui/settings';
+import { extractServiceExtensionDemands, fulfillServiceExtensionDemand } from './utils';
+
+export interface Fulfillments {
+  llm: (demand: LLMDemands) => Promise<LLMFulfillments>;
+  embedding: (demand: EmbeddingDemands) => Promise<EmbeddingFulfillments>;
+  mcp: (demand: MCPDemands) => Promise<MCPFulfillments>;
+  oauth: (demand: OAuthDemands) => Promise<OAuthFulfillments>;
+  settings: (demand: SettingsDemands) => Promise<SettingsFulfillments>;
+  secrets: (demand: SecretDemands) => Promise<SecretFulfillments>;
+  form: (demand: FormDemands) => Promise<FormFulfillments>;
+  oauthRedirectUri: () => string | null;
+  getContextToken: () => ContextToken;
+}
+
+const mcpExtensionExtractor = extractServiceExtensionDemands(mcpExtension);
+const llmExtensionExtractor = extractServiceExtensionDemands(llmExtension);
+const embeddingExtensionExtractor = extractServiceExtensionDemands(embeddingExtension);
+const oauthExtensionExtractor = extractServiceExtensionDemands(oauthProviderExtension);
+const settingsExtensionExtractor = extractServiceExtensionDemands(settingsExtension);
+const secretExtensionExtractor = extractServiceExtensionDemands(secretsExtension);
+const formExtensionExtractor = extractServiceExtensionDemands(formExtension);
+
+const fulfillMcpDemand = fulfillServiceExtensionDemand(mcpExtension);
+const fulfillLlmDemand = fulfillServiceExtensionDemand(llmExtension);
+const fulfillEmbeddingDemand = fulfillServiceExtensionDemand(embeddingExtension);
+const fulfillOAuthDemand = fulfillServiceExtensionDemand(oauthProviderExtension);
+const fulfillSettingsDemand = fulfillServiceExtensionDemand(settingsExtension);
+const fulfillSecretDemand = fulfillServiceExtensionDemand(secretsExtension);
+const fulfillFormDemand = fulfillServiceExtensionDemand(formExtension);
+
+export const handleAgentCard = (agentCard: { capabilities: AgentCapabilities }) => {
+  const extensions = agentCard.capabilities.extensions ?? [];
+
+  const llmDemands = llmExtensionExtractor(extensions);
+  const embeddingDemands = embeddingExtensionExtractor(extensions);
+  const mcpDemands = mcpExtensionExtractor(extensions);
+  const oauthDemands = oauthExtensionExtractor(extensions);
+  const settingsDemands = settingsExtensionExtractor(extensions);
+  const secretDemands = secretExtensionExtractor(extensions);
+  const formDemands = formExtensionExtractor(extensions);
+
+  const resolveMetadata = async (fulfillments: Fulfillments) => {
+    let fulfilledMetadata: Record<string, unknown> = {};
+
+    fulfilledMetadata = platformApiExtension(fulfilledMetadata, fulfillments.getContextToken());
+
+    if (llmDemands) {
+      fulfilledMetadata = fulfillLlmDemand(fulfilledMetadata, await fulfillments.llm(llmDemands));
+    }
+
+    if (embeddingDemands) {
+      fulfilledMetadata = fulfillEmbeddingDemand(fulfilledMetadata, await fulfillments.embedding(embeddingDemands));
+    }
+
+    if (mcpDemands) {
+      fulfilledMetadata = fulfillMcpDemand(fulfilledMetadata, await fulfillments.mcp(mcpDemands));
+    }
+
+    if (oauthDemands) {
+      fulfilledMetadata = fulfillOAuthDemand(fulfilledMetadata, await fulfillments.oauth(oauthDemands));
+    }
+
+    if (settingsDemands) {
+      fulfilledMetadata = fulfillSettingsDemand(fulfilledMetadata, await fulfillments.settings(settingsDemands));
+    }
+
+    if (secretDemands) {
+      fulfilledMetadata = fulfillSecretDemand(fulfilledMetadata, await fulfillments.secrets(secretDemands));
+    }
+
+    if (formDemands) {
+      fulfilledMetadata = fulfillFormDemand(fulfilledMetadata, await fulfillments.form(formDemands));
+    }
+
+    const oauthRedirectUri = fulfillments.oauthRedirectUri();
+    if (oauthRedirectUri) {
+      fulfilledMetadata = {
+        ...fulfilledMetadata,
+        [oauthRequestExtension.getUri()]: {
+          redirect_uri: oauthRedirectUri,
+        },
+      };
+    }
+
+    return fulfilledMetadata;
+  };
+
+  return {
+    resolveMetadata,
+    demands: { llmDemands, embeddingDemands, mcpDemands, oauthDemands, settingsDemands, secretDemands, formDemands },
+  };
+};

package/src/client/a2a/extensions/handle-input-required.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { FormResponseValue } from './common/form';
+import { FormRequestExtension } from './ui/form-request';
+
+export type InputRequiredResponses = Partial<{
+  form: Record<string, FormResponseValue>;
+}>;
+
+export const handleInputRequired = () => {
+  const resolveMetadata = async (responses: InputRequiredResponses) => {
+    const metadata: Record<string, unknown> = {};
+
+    if (responses.form) {
+      metadata[FormRequestExtension.getUri()] = {
+        values: responses.form,
+      };
+    }
+
+    return metadata;
+  };
+
+  return {
+    resolveMetadata,
+  };
+};

package/src/client/a2a/extensions/handle-task-status-update.ts

@@ -0,0 +1,74 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { TaskStatusUpdateEvent } from '@a2a-js/sdk';
+
+import type { FormRender } from './common/form';
+import type { SecretDemands } from './services/secrets';
+import { secretsMessageExtension } from './services/secrets';
+import { FormRequestExtension } from './ui/form-request';
+import { oauthRequestExtension } from './ui/oauth';
+import { extractUiExtensionData } from './utils';
+
+const secretsMessageExtensionExtractor = extractUiExtensionData(secretsMessageExtension);
+const oauthRequestExtensionExtractor = extractUiExtensionData(oauthRequestExtension);
+const FormRequestExtensionExtractor = extractUiExtensionData(FormRequestExtension);
+
+export enum TaskStatusUpdateType {
+  SecretRequired = 'secret-required',
+  FormRequired = 'form-required',
+  OAuthRequired = 'oauth-required',
+}
+
+export interface SecretRequiredResult {
+  type: TaskStatusUpdateType.SecretRequired;
+  demands: SecretDemands;
+}
+
+export interface FormRequiredResult {
+  type: TaskStatusUpdateType.FormRequired;
+  form: FormRender;
+}
+
+export interface OAuthRequiredResult {
+  type: TaskStatusUpdateType.OAuthRequired;
+  url: string;
+}
+
+export type TaskStatusUpdateResult = SecretRequiredResult | FormRequiredResult | OAuthRequiredResult;
+
+export const handleTaskStatusUpdate = (event: TaskStatusUpdateEvent): TaskStatusUpdateResult[] => {
+  const results: TaskStatusUpdateResult[] = [];
+
+  if (event.status.state === 'auth-required') {
+    const secretRequired = secretsMessageExtensionExtractor(event.status.message?.metadata);
+    const oauthRequired = oauthRequestExtensionExtractor(event.status.message?.metadata);
+
+    if (oauthRequired) {
+      results.push({
+        type: TaskStatusUpdateType.OAuthRequired,
+        url: oauthRequired.authorization_endpoint_url,
+      });
+    }
+
+    if (secretRequired) {
+      results.push({
+        type: TaskStatusUpdateType.SecretRequired,
+        demands: secretRequired,
+      });
+    }
+  } else if (event.status.state === 'input-required') {
+    const formRequired = FormRequestExtensionExtractor(event.status.message?.metadata);
+
+    if (formRequired) {
+      results.push({
+        type: TaskStatusUpdateType.FormRequired,
+        form: formRequired,
+      });
+    }
+  }
+
+  return results;
+};

package/src/client/a2a/extensions/services/embedding.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import type { A2AServiceExtension } from '../types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/services/embedding/v1';
+
+const embeddingDemandSchema = z.object({
+  description: z.string().nullish(),
+  suggested: z.array(z.string()).nullish(),
+});
+
+const embeddingDemandsSchema = z.object({
+  embedding_demands: z.record(z.string(), embeddingDemandSchema),
+});
+export type EmbeddingDemands = z.infer<typeof embeddingDemandsSchema>;
+
+const embeddingFulfillmentsSchema = z.object({
+  embedding_fulfillments: z.record(
+    z.string(),
+    z.object({
+      identifier: z.string().nullish(),
+      api_base: z.string(),
+      api_key: z.string(),
+      api_model: z.string(),
+    }),
+  ),
+});
+export type EmbeddingFulfillments = z.infer<typeof embeddingFulfillmentsSchema>;
+
+export const embeddingExtension: A2AServiceExtension<
+  typeof URI,
+  z.infer<typeof embeddingDemandsSchema>,
+  EmbeddingFulfillments
+> = {
+  getUri: () => URI,
+  getDemandsSchema: () => embeddingDemandsSchema,
+  getFulfillmentSchema: () => embeddingFulfillmentsSchema,
+};

package/src/client/a2a/extensions/services/form.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import { formRenderSchema, formResponseSchema } from '../common/form';
+import type { A2AServiceExtension } from '../types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/services/form/v1';
+
+const formDemandSchema = z.object({
+  form_demands: z
+    .object({
+      initial_form: formRenderSchema,
+    })
+    .partial(),
+});
+export type FormDemands = z.infer<typeof formDemandSchema>;
+
+const formFulfillmentSchema = z.object({
+  form_fulfillments: z.record(z.string(), formResponseSchema),
+});
+export type FormFulfillments = z.infer<typeof formFulfillmentSchema>;
+
+export const formExtension: A2AServiceExtension<typeof URI, FormDemands, FormFulfillments> = {
+  getDemandsSchema: () => formDemandSchema,
+  getFulfillmentSchema: () => formFulfillmentSchema,
+  getUri: () => URI,
+};

package/src/client/a2a/extensions/services/llm.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import type { A2AServiceExtension } from '../types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/services/llm/v1';
+
+const llmDemandSchema = z.object({
+  description: z.string().nullish(),
+  suggested: z.array(z.string()).nullish(),
+});
+
+const llmDemandsSchema = z.object({
+  llm_demands: z.record(z.string(), llmDemandSchema),
+});
+export type LLMDemands = z.infer<typeof llmDemandsSchema>;
+
+const llmFulfillmentSchema = z.object({
+  llm_fulfillments: z.record(
+    z.string(),
+    z.object({
+      identifier: z.string().nullish(),
+      api_base: z.string(),
+      api_key: z.string(),
+      api_model: z.string(),
+    }),
+  ),
+});
+export type LLMFulfillments = z.infer<typeof llmFulfillmentSchema>;
+
+export const llmExtension: A2AServiceExtension<typeof URI, z.infer<typeof llmDemandsSchema>, LLMFulfillments> = {
+  getUri: () => URI,
+  getDemandsSchema: () => llmDemandsSchema,
+  getFulfillmentSchema: () => llmFulfillmentSchema,
+};

package/src/client/a2a/extensions/services/mcp.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import type { A2AServiceExtension } from '../types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/services/mcp/v1';
+
+const mcpTransportTypesEnum = z.enum(['streamable_http', 'stdio']);
+type MCPTransportType = z.infer<typeof mcpTransportTypesEnum>;
+
+const mcpDemandSchema = z.object({
+  description: z.string().nullish(),
+  suggested: z.array(z.string()).nullish(),
+  allowed_transports: z.array(mcpTransportTypesEnum).nullish(),
+});
+
+const mcpDemandsSchema = z.object({
+  mcp_demands: z.record(z.string(), mcpDemandSchema),
+});
+export type MCPDemands = z.infer<typeof mcpDemandsSchema>;
+
+const mcpFulfillmentSchema = z.object({
+  mcp_fulfillments: z.record(
+    z.string(),
+    z.object({
+      transport: z.object({
+        type: mcpTransportTypesEnum,
+        url: z.string(),
+        headers: z.record(z.string(), z.string()).optional(),
+      }),
+    }),
+  ),
+});
+export type MCPFulfillments = z.infer<typeof mcpFulfillmentSchema>;
+
+export const mcpExtension: A2AServiceExtension<
+  typeof URI,
+  z.infer<typeof mcpDemandsSchema>,
+  {
+    mcp_fulfillments: Record<
+      string,
+      {
+        transport: {
+          type: MCPTransportType;
+          url: string;
+          headers?: Record<string, string>;
+        };
+      }
+    >;
+  }
+> = {
+  getUri: () => URI,
+  getDemandsSchema: () => mcpDemandsSchema,
+  getFulfillmentSchema: () => mcpFulfillmentSchema,
+};

package/src/client/a2a/extensions/services/oauth-provider.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import type { A2AServiceExtension } from '../types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/auth/oauth/v1';
+
+const oauthDemandSchema = z.object({
+  redirect_uri: z.boolean(),
+});
+
+const oauthDemandsSchema = z.object({
+  oauth_demands: z.record(z.string(), oauthDemandSchema),
+});
+export type OAuthDemands = z.infer<typeof oauthDemandsSchema>;
+
+const oauthFulfillmentSchema = z.object({
+  oauth_fulfillments: z.record(
+    z.string(),
+    z.object({
+      redirect_uri: z.string(),
+    }),
+  ),
+});
+export type OAuthFulfillments = z.infer<typeof oauthFulfillmentSchema>;
+
+export const oauthProviderExtension: A2AServiceExtension<
+  typeof URI,
+  z.infer<typeof oauthDemandsSchema>,
+  {
+    oauth_fulfillments: Record<
+      string,
+      {
+        redirect_uri: string;
+      }
+    >;
+  }
+> = {
+  getUri: () => URI,
+  getDemandsSchema: () => oauthDemandsSchema,
+  getFulfillmentSchema: () => oauthFulfillmentSchema,
+};
+
+export const oauthMessageSchema = z.object({
+  data: z.object({
+    redirect_uri: z.string(),
+  }),
+});

package/src/client/a2a/extensions/services/platform.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ContextToken } from '../../../api/types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/services/platform_api/v1';
+
+const getMetadata = (contextToken: ContextToken) => {
+  return {
+    auth_token: contextToken.token,
+    expires_at: contextToken.expires_at,
+  };
+};
+
+export const platformApiExtension = (metadata: Record<string, unknown>, contextToken: ContextToken) => {
+  return {
+    ...metadata,
+    [URI]: getMetadata(contextToken),
+  };
+};

package/src/client/a2a/extensions/services/secrets.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import type { A2AServiceExtension, A2AUiExtension } from '../types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/auth/secrets/v1';
+
+const secretDemandSchema = z.object({
+  name: z.string(),
+  description: z.string().nullish(),
+});
+export type SecretDemand = z.infer<typeof secretDemandSchema>;
+
+const secretDemandsSchema = z.object({
+  secret_demands: z.record(z.string(), secretDemandSchema),
+});
+export type SecretDemands = z.infer<typeof secretDemandsSchema>;
+
+const secretFulfillmentSchema = z.object({
+  secret_fulfillments: z.record(
+    z.string(),
+    z.object({
+      secret: z.string(),
+    }),
+  ),
+});
+export type SecretFulfillments = z.infer<typeof secretFulfillmentSchema>;
+
+export const secretsExtension: A2AServiceExtension<
+  typeof URI,
+  z.infer<typeof secretDemandsSchema>,
+  SecretFulfillments
+> = {
+  getUri: () => URI,
+  getDemandsSchema: () => secretDemandsSchema,
+  getFulfillmentSchema: () => secretFulfillmentSchema,
+};
+
+export const secretsMessageExtension: A2AUiExtension<typeof URI, SecretDemands> = {
+  getMessageMetadataSchema: () => z.object({ [URI]: secretDemandsSchema }).partial(),
+  getUri: () => URI,
+};

package/src/client/a2a/extensions/types.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { z } from 'zod';
+
+export interface A2AExtension<U extends string> {
+  getUri: () => U;
+}
+
+export interface A2AUiExtension<U extends string, D> extends A2AExtension<U> {
+  getMessageMetadataSchema: () => z.ZodSchema<Partial<Record<U, D>>>;
+}
+
+export interface A2AServiceExtension<U extends string, D, F> extends A2AExtension<U> {
+  getUri: () => U;
+  getDemandsSchema: () => z.ZodSchema<D>;
+  getFulfillmentSchema: () => z.ZodSchema<F>;
+}

package/src/client/a2a/extensions/ui/agent-detail.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import { interactionModeSchema } from '../../../../types';
+import type { A2AUiExtension } from '../types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/ui/agent-detail/v1';
+
+const contributorSchema = z.object({
+  name: z.string(),
+  email: z.string().nullish(),
+  url: z.string().nullish(),
+});
+
+const toolSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+});
+
+const schema = z.object({
+  interaction_mode: z.union([interactionModeSchema, z.string()]).nullish(),
+  user_greeting: z.string().nullish(),
+  input_placeholder: z.string().nullish(),
+  tools: z.array(toolSchema).nullish(),
+  framework: z.string().nullish(),
+  license: z.string().nullish(),
+  programming_language: z.string().nullish(),
+  homepage_url: z.string().nullish(),
+  source_code_url: z.string().nullish(),
+  container_image_url: z.string().nullish(),
+  author: contributorSchema.nullish(),
+  contributors: z.array(contributorSchema).nullish(),
+});
+
+export type AgentDetailTool = z.infer<typeof toolSchema>;
+export type AgentDetailContributor = z.infer<typeof contributorSchema>;
+export type AgentDetail = z.infer<typeof schema>;
+
+export const agentDetailExtension: A2AUiExtension<typeof URI, AgentDetail> = {
+  getMessageMetadataSchema: () => z.object({ [URI]: schema }).partial(),
+  getUri: () => URI,
+};

package/src/client/a2a/extensions/ui/citation.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import type { A2AUiExtension } from '../types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/ui/citation/v1';
+
+const citationSchema = z.object({
+  url: z.string().nullish(),
+  start_index: z.number().nullish(),
+  end_index: z.number().nullish(),
+  title: z.string().nullish(),
+  description: z.string().nullish(),
+});
+
+const schema = z.object({
+  citations: z.array(citationSchema),
+});
+
+export type CitationMetadata = z.infer<typeof schema>;
+export type Citation = z.infer<typeof citationSchema>;
+
+export const citationExtension: A2AUiExtension<typeof URI, CitationMetadata> = {
+  getMessageMetadataSchema: () => z.object({ [URI]: schema }).partial(),
+  getUri: () => URI,
+};

package/src/client/a2a/extensions/ui/form-request.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import { formRenderSchema } from '../common/form';
+import type { A2AUiExtension } from '../types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/ui/form_request/v1';
+
+export type FormRequest = z.infer<typeof formRenderSchema>;
+
+export const FormRequestExtension: A2AUiExtension<typeof URI, FormRequest> = {
+  getMessageMetadataSchema: () => z.object({ [URI]: formRenderSchema }).partial(),
+  getUri: () => URI,
+};

package/src/client/a2a/extensions/ui/oauth.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+import type { A2AUiExtension } from '../types';
+
+const URI = 'https://a2a-extensions.agentstack.beeai.dev/auth/oauth/v1';
+
+const schema = z.object({
+  authorization_endpoint_url: z.string(),
+});
+
+export type OAuthRequest = z.infer<typeof schema>;
+
+export const oauthRequestExtension: A2AUiExtension<typeof URI, OAuthRequest> = {
+  getMessageMetadataSchema: () => z.object({ [URI]: schema }).partial(),
+  getUri: () => URI,
+};