agentstack-sdk 0.4.2-rc1

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

@@ -0,0 +1,84 @@
+/**
+ * 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/ui/settings/v1';
+
+const checkboxField = z.object({
+  id: z.string().nonempty(),
+  label: z.string().nonempty(),
+  default_value: z.boolean(),
+});
+
+const checkboxGroupField = z.object({
+  id: z.string().nonempty(),
+  type: z.literal('checkbox_group'),
+  fields: z.array(checkboxField),
+});
+
+const optionItem = z.object({
+  label: z.string().nonempty(),
+  value: z.string().nonempty(),
+});
+
+const singleSelectField = z.object({
+  type: z.literal('single_select'),
+  id: z.string().nonempty(),
+  label: z.string().nonempty(),
+  options: z.array(optionItem).nonempty(),
+  default_value: z.string().nonempty(),
+});
+
+const settingsRenderSchema = z.object({
+  fields: z.array(z.discriminatedUnion('type', [checkboxGroupField, singleSelectField])),
+});
+
+const checkboxFieldValue = z.object({
+  value: z.boolean(),
+});
+
+const checkboxGroupFieldValue = z.object({
+  type: z.literal('checkbox_group'),
+  values: z.record(z.string(), checkboxFieldValue),
+});
+
+const singleSelectFieldValue = z.object({
+  type: z.literal('single_select'),
+  value: z.string(),
+});
+
+const settingsFieldValue = z.discriminatedUnion('type', [checkboxGroupFieldValue, singleSelectFieldValue]);
+
+export const agentSettings = z.record(z.string(), settingsFieldValue);
+export type AgentSettings = z.infer<typeof agentSettings>;
+
+const agentRunSettingsSchema = z.object({
+  values: agentSettings,
+});
+
+export type SettingsCheckboxField = z.infer<typeof checkboxField>;
+export type SettingsCheckboxGroupField = z.infer<typeof checkboxGroupField>;
+export type SettingsOptionItem = z.infer<typeof optionItem>;
+export type SettingsSingleSelectField = z.infer<typeof singleSelectField>;
+export type SettingsCheckboxFieldValue = z.infer<typeof checkboxFieldValue>;
+export type SettingsCheckboxGroupFieldValue = z.infer<typeof checkboxGroupFieldValue>;
+export type SettingsSingleSelectFieldValue = z.infer<typeof singleSelectFieldValue>;
+export type SettingsFieldValue = z.infer<typeof settingsFieldValue>;
+
+export type SettingsDemands = z.infer<typeof settingsRenderSchema>;
+export type SettingsFulfillments = z.infer<typeof agentRunSettingsSchema>;
+
+export const settingsExtension: A2AServiceExtension<
+  typeof URI,
+  z.infer<typeof settingsRenderSchema>,
+  SettingsFulfillments
+> = {
+  getDemandsSchema: () => settingsRenderSchema,
+  getFulfillmentSchema: () => agentRunSettingsSchema,
+  getUri: () => URI,
+};

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

@@ -0,0 +1,23 @@
+/**
+ * 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/trajectory/v1';
+
+const schema = z.object({
+  title: z.string().nullish(),
+  content: z.string().nullish(),
+  group_id: z.string().nullish(),
+});
+
+export type TrajectoryMetadata = z.infer<typeof schema>;
+
+export const trajectoryExtension: A2AUiExtension<typeof URI, TrajectoryMetadata> = {
+  getMessageMetadataSchema: () => z.object({ [URI]: schema }).partial(),
+  getUri: () => URI,
+};

package/src/client/a2a/extensions/utils/build-message-builder.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { AgentCapabilities, Message } from '@a2a-js/sdk';
+
+import type { Fulfillments } from '../handle-agent-card';
+import { handleAgentCard } from '../handle-agent-card';
+
+export const buildMessageBuilder =
+  (agent: { capabilities: AgentCapabilities }) =>
+  async (
+    contextId: string,
+    fulfillments: Fulfillments,
+    originalMessage: Pick<Message, 'parts' | 'messageId'>,
+  ): Promise<Message> => {
+    const { resolveMetadata } = handleAgentCard(agent);
+    const metadata = await resolveMetadata(fulfillments);
+
+    return {
+      ...originalMessage,
+      contextId,
+      kind: 'message',
+      role: 'user',
+      metadata,
+    } as const;
+  };

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

@@ -0,0 +1,66 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { AgentExtension } from '@a2a-js/sdk';
+
+import type { A2AServiceExtension, A2AUiExtension } from './types';
+
+export function extractUiExtensionData<U extends string, D>(extension: A2AUiExtension<U, D>) {
+  const schema = extension.getMessageMetadataSchema();
+  const uri = extension.getUri();
+
+  return function (metadata: Record<string, unknown> | undefined) {
+    const { success, data: parsed, error } = schema.safeParse(metadata ?? {});
+
+    if (!success) {
+      console.warn(error);
+    }
+
+    if (!success) {
+      return null;
+    }
+
+    return parsed[uri];
+  };
+}
+
+export function extractServiceExtensionDemands<U extends string, D, F>(extension: A2AServiceExtension<U, D, F>) {
+  const schema = extension.getDemandsSchema();
+  const uri = extension.getUri();
+
+  return function (agentExtensions: AgentExtension[]) {
+    const foundExtension = agentExtensions.find((agentExtension) => agentExtension.uri === uri);
+    if (!foundExtension?.params) {
+      return null;
+    }
+    const { success, data: parsed, error } = schema.safeParse(foundExtension.params);
+
+    if (!success) {
+      console.warn(error);
+
+      return null;
+    }
+
+    return parsed;
+  };
+}
+
+export function fulfillServiceExtensionDemand<U extends string, D, F>(extension: A2AServiceExtension<U, D, F>) {
+  const schema = extension.getFulfillmentSchema();
+  const uri = extension.getUri();
+
+  return function (metadata: Record<string, unknown>, fulfillment: F) {
+    const { success, data: parsed, error } = schema.safeParse(fulfillment);
+
+    if (!success) {
+      console.warn(error);
+    }
+
+    return {
+      ...metadata,
+      [uri]: success ? parsed : {},
+    };
+  };
+}

package/src/client/api/build-api-client.ts

@@ -0,0 +1,74 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { z } from 'zod';
+
+import type { ContextPermissionGrant, GlobalPermissionGrant, ModelCapability } from './types';
+import { contextSchema, contextTokenSchema, modelProviderMatchSchema } from './types';
+
+export const buildApiClient = ({ baseUrl }: { baseUrl: string } = { baseUrl: '' }) => {
+  async function callApi<T>(method: 'POST', url: string, data: Record<string, unknown>, resultSchema: z.ZodSchema<T>) {
+    const response = await fetch(`${baseUrl}${url}`, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(data),
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to call Agent Stackk API - ${url}`);
+    }
+
+    const json = await response.json();
+    return resultSchema.parse(json);
+  }
+
+  const createContext = async (providerId: string) => {
+    const { id: contextId } = await callApi(
+      'POST',
+      '/api/v1/contexts',
+      { metadata: {}, provider_id: providerId },
+      contextSchema,
+    );
+
+    return contextId;
+  };
+
+  const createContextToken = async (
+    contextId: string,
+    globalPermissions: GlobalPermissionGrant,
+    contextPermissions: ContextPermissionGrant,
+  ) => {
+    const token = await callApi(
+      'POST',
+      `/api/v1/contexts/${contextId}/token`,
+      {
+        context_id: contextId,
+        grant_global_permissions: globalPermissions,
+        grant_context_permissions: contextPermissions,
+      },
+      contextTokenSchema,
+    );
+
+    return { token, contextId };
+  };
+
+  const matchProviders = async (suggestedModels: string[], capability: ModelCapability, scoreCutoff: number) => {
+    return await callApi(
+      'POST',
+      '/api/v1/model_providers/match',
+      {
+        capability,
+        score_cutoff: scoreCutoff,
+        suggested_models: suggestedModels,
+      },
+      modelProviderMatchSchema,
+    );
+  };
+
+  return { createContextToken, createContext, matchProviders };
+};
+
+export type AgentstackClient = ReturnType<typeof buildApiClient>;

package/src/client/api/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { z } from 'zod';
+
+export const contextSchema = z.object({
+  id: z.string(),
+  created_at: z.string().optional(),
+  created_by: z.string(),
+  last_active_at: z.string(),
+  provider_id: z.string().nullable(),
+  updated_at: z.string(),
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+});
+
+export const contextTokenSchema = z.object({
+  token: z.string(),
+  expires_at: z.string().nullable(),
+});
+export type ContextToken = z.infer<typeof contextTokenSchema>;
+
+export enum ModelCapability {
+  Llm = 'llm',
+  Embedding = 'embedding',
+}
+
+const paginatedResultSchema = z.object({
+  items: z.array(z.unknown()),
+  total_count: z.number(),
+  has_more: z.boolean(),
+  next_page_token: z.string().nullable(),
+});
+
+export const modelProviderMatchSchema = paginatedResultSchema.extend({
+  items: z.array(
+    z.object({
+      model_id: z.string(),
+      score: z.number(),
+    }),
+  ),
+});
+export type ModelProviderMatch = z.infer<typeof modelProviderMatchSchema>;
+
+interface ResourceIdPermission {
+  id: string;
+}
+
+export interface GlobalPermissionGrant {
+  a2a_proxy?: '*'[];
+  connectors?: ('read' | 'write' | 'proxy' | '*')[];
+  context_data?: ('read' | 'write' | '*')[];
+  contexts?: ('read' | 'write' | '*')[];
+  embeddings?: ('*' | ResourceIdPermission)[];
+  feedback?: 'write'[];
+  files?: ('read' | 'write' | 'extract' | '*')[];
+  llm?: ('*' | ResourceIdPermission)[];
+  mcp_providers?: ('read' | 'write' | '*')[];
+  mcp_proxy?: '*'[];
+  mcp_tools?: ('read' | '*')[];
+  model_providers?: ('read' | 'write' | '*')[];
+  provider_variables?: ('read' | 'write' | '*')[];
+  providers?: ('read' | 'write' | '*')[];
+  vector_stores?: ('read' | 'write' | 'extract' | '*')[];
+}
+
+export interface ContextPermissionGrant {
+  context_data?: ('read' | 'write' | '*')[];
+  files?: ('read' | 'write' | 'extract' | '*')[];
+  vector_stores?: ('read' | 'write' | 'extract' | '*')[];
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from './client/a2a/extensions/common/form';
+export * from './client/a2a/extensions/fulfillment-resolvers/build-llm-extension-fulfillment-resolver';
+export { type Fulfillments, handleAgentCard } from './client/a2a/extensions/handle-agent-card';
+export { handleInputRequired, type InputRequiredResponses } from './client/a2a/extensions/handle-input-required';
+export {
+  handleTaskStatusUpdate,
+  type TaskStatusUpdateResult,
+  TaskStatusUpdateType,
+} from './client/a2a/extensions/handle-task-status-update';
+export * from './client/a2a/extensions/services/embedding';
+export * from './client/a2a/extensions/services/form';
+export * from './client/a2a/extensions/services/llm';
+export * from './client/a2a/extensions/services/mcp';
+export * from './client/a2a/extensions/services/oauth-provider';
+export * from './client/a2a/extensions/services/platform';
+export * from './client/a2a/extensions/services/secrets';
+export * from './client/a2a/extensions/types';
+export * from './client/a2a/extensions/ui/agent-detail';
+export * from './client/a2a/extensions/ui/citation';
+export * from './client/a2a/extensions/ui/form-request';
+export * from './client/a2a/extensions/ui/oauth';
+export * from './client/a2a/extensions/ui/settings';
+export * from './client/a2a/extensions/ui/trajectory';
+export * from './client/a2a/extensions/utils';
+export * from './client/a2a/extensions/utils/build-message-builder';
+export * from './client/api/build-api-client';
+export * from './client/api/types';

package/src/types.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import z from 'zod';
+
+export const interactionModeSchema = z.enum(['single-turn', 'multi-turn']);
+export type InteractionMode = z.infer<typeof interactionModeSchema>;