feat: extending TS sdk (#1609)

* feat: extending TS sdk

Signed-off-by: Tomas Weiss <[email protected]>

* fix: code review comments

Signed-off-by: Tomas Weiss <[email protected]>

* fix: remove GET from the callApi function, still keep the method for extensibility in the future

Signed-off-by: Tomas Weiss <[email protected]>

* chore: cleanup package.json

Signed-off-by: Tomas Weiss <[email protected]>

* chore: testing release pipeline

Signed-off-by: Tomas Weiss <[email protected]>

* chore: install mise

Signed-off-by: Tomas Weiss <[email protected]>

* fix: no git checks

Signed-off-by: Tomas Weiss <[email protected]>

* chore: setup release action

Signed-off-by: Tomas Weiss <[email protected]>

* fix: code review commnets

Signed-off-by: Tomas Weiss <[email protected]>

---------

Signed-off-by: Tomas Weiss <[email protected]>

Author: tomkis

.github/workflows/release.yml

@@ -151,3 +151,7 @@ jobs:
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages-dir: apps/agentstack-cli/dist
+
+      - name: Publish TS SDK
+        working-directory: apps/agentstack-sdk-ts
+        run: pnpm publish --access public --no-git-checks

apps/agentstack-sdk-ts/package.json

@@ -32,6 +32,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "src/**/*",
     "dist/**/*",
     "package.json"
   ],

apps/agentstack-sdk-ts/src/client/a2a/extensions/fulfillment-resolvers/build-llm-extension-fulfillment-resolver.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { AgentstackClient } from '../../../api/build-api-client';
+import type { ContextToken } from '../../../api/types';
+import { ModelCapability } from '../../../api/types';
+import type { LLMDemands, LLMFulfillments } from '../services/llm';
+
+const DEFAULT_SCORE_CUTOFF = 0.4;
+
+export const buildLLMExtensionFulfillmentResolver = (api: AgentstackClient, token: ContextToken) => {
+  return async ({ llm_demands }: LLMDemands): Promise<LLMFulfillments> => {
+    const allDemands = Object.keys(llm_demands);
+    const fulfillmentPromises = allDemands.map(async (demandKey) => {
+      const demand = llm_demands[demandKey];
+      const resolvedModels = await api.matchProviders({
+        suggestedModels: demand.suggested ?? [],
+        capability: ModelCapability.Llm,
+        scoreCutoff: DEFAULT_SCORE_CUTOFF,
+      });
+
+      if (resolvedModels.items.length === 0) {
+        throw new Error(`No models found for demand ${demandKey}. Demand details: ${JSON.stringify(demand)}`);
+      }
+
+      return [
+        demandKey,
+        {
+          identifier: 'llm_proxy',
+          // {platform_url} is replaced by the server SDK to the platform URL
+          api_base: '{platform_url}/api/v1/openai/',
+          api_key: token.token,
+          api_model: resolvedModels.items[0].model_id,
+        },
+      ] as const;
+    });
+
+    const fulfilledEntries = await Promise.all(fulfillmentPromises);
+    return { llm_fulfillments: Object.fromEntries(fulfilledEntries) };
+  };
+};

apps/agentstack-sdk-ts/src/client/a2a/extensions/handle-agent-card.ts

@@ -5,7 +5,7 @@
 
 import type { AgentCapabilities } from '@a2a-js/sdk';
 
-import type { ContextToken } from '../../context/types';
+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';

apps/agentstack-sdk-ts/src/client/a2a/extensions/services/platform.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { ContextToken } from '../../../context/types';
+import type { ContextToken } from '../../../api/types';
 
 const URI = 'https://a2a-extensions.agentstack.beeai.dev/services/platform_api/v1';
 

apps/agentstack-sdk-ts/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;
+  };

apps/agentstack-sdk-ts/src/client/api/build-api-client.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { z } from 'zod';
+
+import type { ContextPermissionsGrant, GlobalPermissionsGrant, ModelCapability } from './types';
+import { contextSchema, contextTokenSchema, modelProviderMatchSchema } from './types';
+
+interface MatchProvidersParams {
+  suggestedModels: string[] | null;
+  capability: ModelCapability;
+  scoreCutoff: number;
+}
+
+interface CreateContextTokenParams {
+  contextId: string;
+  globalPermissions: GlobalPermissionsGrant;
+  contextPermissions: ContextPermissionsGrant;
+}
+
+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 context = await callApi('POST', '/api/v1/contexts', { metadata: {}, provider_id: providerId }, contextSchema);
+
+    return context;
+  };
+
+  const createContextToken = async ({ contextId, globalPermissions, contextPermissions }: CreateContextTokenParams) => {
+    const token = await callApi(
+      'POST',
+      `/api/v1/contexts/${contextId}/token`,
+      {
+        grant_global_permissions: globalPermissions,
+        grant_context_permissions: contextPermissions,
+      },
+      contextTokenSchema,
+    );
+
+    return { token, contextId };
+  };
+
+  const matchProviders = async ({ suggestedModels, capability, scoreCutoff }: MatchProvidersParams) => {
+    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>;

apps/agentstack-sdk-ts/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(),
+  updated_at: z.string(),
+  last_active_at: z.string(),
+  created_by: z.string(),
+  provider_id: z.string().nullable(),
+  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 ContextPermissionsGrant {
+  files?: ('read' | 'write' | 'extract' | '*')[];
+  vector_stores?: ('read' | 'write' | '*')[];
+  context_data?: ('read' | 'write' | '*')[];
+}
+
+export interface GlobalPermissionsGrant extends ContextPermissionsGrant {
+  llm?: ('*' | ResourceIdPermission)[];
+  embeddings?: ('*' | ResourceIdPermission)[];
+  a2a_proxy?: '*'[];
+  model_providers?: ('read' | 'write' | '*')[];
+  variables?: ('read' | 'write' | '*')[];
+
+  providers?: ('read' | 'write' | '*')[];
+  provider_variables?: ('read' | 'write' | '*')[];
+
+  contexts?: ('read' | 'write' | '*')[];
+  mcp_providers?: ('read' | 'write' | '*')[];
+  mcp_tools?: ('read' | '*')[];
+  mcp_proxy?: '*'[];
+
+  connectors?: ('read' | 'write' | 'proxy' | '*')[];
+}

apps/agentstack-sdk-ts/src/client/context/types.ts

@@ -4,6 +4,7 @@
  */
 
 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 {
@@ -26,4 +27,6 @@ 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/context/types';
+export * from './client/a2a/extensions/utils/build-message-builder';
+export * from './client/api/build-api-client';
+export * from './client/api/types';