@valon-technologies/gestalt 0.0.1-alpha.13 → 0.0.1-alpha.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valon-technologies/gestalt",
-  "version": "0.0.1-alpha.13",
+  "version": "0.0.1-alpha.16",
   "description": "TypeScript SDK for Gestalt executable providers",
   "type": "module",
   "repository": {
@@ -12,6 +12,7 @@
     "./build": "./src/build.ts",
     "./runtime": "./src/runtime.ts",
     "./schema": "./src/schema.ts",
+    "./telemetry": "./src/telemetry.ts",
     "./target": "./src/target.ts"
   },
   "bin": {
@@ -34,13 +35,14 @@
     "docs:build:deploy": "typedoc --options typedoc.json --out ../../docs/public/api/typescript",
     "docs:check": "bun run docs:lint && bun run docs:build",
     "typecheck": "tsc --noEmit",
-    "test": "bun test",
-    "check": "bun test && tsc --noEmit"
+    "test": "bun test --max-concurrency 1",
+    "check": "bun run test && tsc --noEmit"
   },
   "dependencies": {
     "@bufbuild/protobuf": "2.11.0",
     "@connectrpc/connect": "2.1.0",
     "@connectrpc/connect-node": "2.1.0",
+    "@opentelemetry/api": "1.9.0",
     "yaml": "2.8.1"
   },
   "devDependencies": {

package/src/agent.ts

@@ -1,11 +1,17 @@
-import { connect } from "node:net";
-
-import { create, type MessageInitShape } from "@bufbuild/protobuf";
+import {
+  create,
+  fromJson,
+  isMessage,
+  type JsonValue,
+  type MessageInitShape,
+} from "@bufbuild/protobuf";
+import { ValueSchema, type Value } from "@bufbuild/protobuf/wkt";
 import {
   Code,
   ConnectError,
   createClient,
   type Client,
+  type Interceptor,
   type ServiceImpl,
 } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
@@ -22,6 +28,7 @@ import {
   AgentSessionSchema,
   AgentSessionState,
   AgentToolSourceMode,
+  AgentTurnDisplaySchema,
   AgentTurnEventSchema,
   AgentTurnSchema,
   GetAgentProviderCapabilitiesRequestSchema,
@@ -40,8 +47,8 @@ import {
   type AgentSession,
   type AgentToolRef,
   type AgentTurn,
+  type AgentTurnDisplay,
   type AgentTurnEvent,
-  type BoundAgentToolTarget,
   type CancelAgentProviderTurnRequest,
   type CreateAgentProviderSessionRequest,
   type CreateAgentProviderTurnRequest,
@@ -51,18 +58,25 @@ import {
   type GetAgentProviderInteractionRequest,
   type GetAgentProviderSessionRequest,
   type GetAgentProviderTurnRequest,
+  type ListAgentToolsRequest,
+  type ListAgentToolsResponse,
   type ListAgentProviderInteractionsRequest,
   type ListAgentProviderSessionsRequest,
   type ListAgentProviderTurnEventsRequest,
   type ListAgentProviderTurnsRequest,
+  type ListedAgentTool,
   type ResolveAgentProviderInteractionRequest,
   type ResolvedAgentTool,
+  type SearchAgentToolsRequest,
+  type SearchAgentToolsResponse,
   type UpdateAgentProviderSessionRequest,
 } from "../gen/v1/agent_pb.ts";
 import { errorMessage, type MaybePromise } from "./api.ts";
 import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
 
 export const ENV_AGENT_HOST_SOCKET = "GESTALT_AGENT_HOST_SOCKET";
+export const ENV_AGENT_HOST_SOCKET_TOKEN = `${ENV_AGENT_HOST_SOCKET}_TOKEN`;
+const AGENT_HOST_RELAY_TOKEN_HEADER = "x-gestalt-host-service-relay-token";
 
 export type {
   AgentActor,
@@ -76,8 +90,8 @@ export type {
   AgentSession,
   AgentToolRef,
   AgentTurn,
+  AgentTurnDisplay,
   AgentTurnEvent,
-  BoundAgentToolTarget,
   CancelAgentProviderTurnRequest,
   CreateAgentProviderSessionRequest,
   CreateAgentProviderTurnRequest,
@@ -87,12 +101,17 @@ export type {
   GetAgentProviderInteractionRequest,
   GetAgentProviderSessionRequest,
   GetAgentProviderTurnRequest,
+  ListAgentToolsRequest,
+  ListAgentToolsResponse,
   ListAgentProviderInteractionsRequest,
   ListAgentProviderSessionsRequest,
   ListAgentProviderTurnEventsRequest,
   ListAgentProviderTurnsRequest,
+  ListedAgentTool,
   ResolveAgentProviderInteractionRequest,
   ResolvedAgentTool,
+  SearchAgentToolsRequest,
+  SearchAgentToolsResponse,
   UpdateAgentProviderSessionRequest,
 };
 export {
@@ -104,6 +123,27 @@ export {
   AgentToolSourceMode,
 };
 
+export type AgentTurnDisplayValue =
+  | JsonValue
+  | Value
+  | MessageInitShape<typeof ValueSchema>;
+
+export type AgentTurnDisplayInit = Omit<
+  MessageInitShape<typeof AgentTurnDisplaySchema>,
+  "$typeName" | "input" | "output" | "error"
+> & {
+  input?: AgentTurnDisplayValue | undefined;
+  output?: AgentTurnDisplayValue | undefined;
+  error?: AgentTurnDisplayValue | undefined;
+};
+
+export type AgentTurnEventInit = Omit<
+  MessageInitShape<typeof AgentTurnEventSchema>,
+  "$typeName" | "display"
+> & {
+  display?: AgentTurnDisplayInit | undefined;
+};
+
 export interface AgentProviderOptions extends RuntimeProviderOptions {
   createSession?: (
     request: CreateAgentProviderSessionRequest,
@@ -131,7 +171,7 @@ export interface AgentProviderOptions extends RuntimeProviderOptions {
   ) => MaybePromise<MessageInitShape<typeof AgentTurnSchema>>;
   listTurnEvents?: (
     request: ListAgentProviderTurnEventsRequest,
-  ) => MaybePromise<MessageInitShape<typeof AgentTurnEventSchema>[]>;
+  ) => MaybePromise<AgentTurnEventInit[]>;
   getInteraction?: (
     request: GetAgentProviderInteractionRequest,
   ) => MaybePromise<MessageInitShape<typeof AgentInteractionSchema>>;
@@ -262,7 +302,7 @@ export class AgentProvider extends RuntimeProvider {
 
   async listTurnEvents(
     request: ListAgentProviderTurnEventsRequest,
-  ): Promise<MessageInitShape<typeof AgentTurnEventSchema>[]> {
+  ): Promise<AgentTurnEventInit[]> {
     return await requireAgentProviderHandler(
       "list turn events",
       this.listTurnEventsHandler,
@@ -318,6 +358,56 @@ export function defineAgentProvider(options: AgentProviderOptions): AgentProvide
   return new AgentProvider(options);
 }
 
+function normalizeAgentTurnEvents(
+  events: AgentTurnEventInit[],
+): MessageInitShape<typeof AgentTurnEventSchema>[] {
+  return events.map((event) => normalizeAgentTurnEvent(event));
+}
+
+function normalizeAgentTurnEvent(
+  event: AgentTurnEventInit,
+): MessageInitShape<typeof AgentTurnEventSchema> {
+  const display = event.display;
+  if (!display) {
+    return event as MessageInitShape<typeof AgentTurnEventSchema>;
+  }
+  return {
+    ...event,
+    display: {
+      ...display,
+      input: normalizeAgentTurnDisplayValue(display.input),
+      output: normalizeAgentTurnDisplayValue(display.output),
+      error: normalizeAgentTurnDisplayValue(display.error),
+    },
+  } as MessageInitShape<typeof AgentTurnEventSchema>;
+}
+
+function normalizeAgentTurnDisplayValue(value: unknown): Value | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (isMessage(value, ValueSchema)) {
+    return value;
+  }
+  if (isValueInit(value)) {
+    return create(ValueSchema, value);
+  }
+  return fromJson(ValueSchema, value as JsonValue);
+}
+
+function isValueInit(value: unknown): value is MessageInitShape<typeof ValueSchema> {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const kind = (value as { kind?: unknown }).kind;
+  return (
+    kind !== null &&
+    typeof kind === "object" &&
+    typeof (kind as { case?: unknown }).case === "string" &&
+    "value" in kind
+  );
+}
+
 export function isAgentProvider(value: unknown): value is AgentProvider {
   return (
     value instanceof AgentProvider ||
@@ -334,15 +424,14 @@ export class AgentHost {
   private readonly client: Client<typeof AgentHostService>;
 
   constructor() {
-    const socketPath = process.env[ENV_AGENT_HOST_SOCKET];
-    if (!socketPath) {
+    const target = process.env[ENV_AGENT_HOST_SOCKET];
+    if (!target) {
       throw new Error(`agent host: ${ENV_AGENT_HOST_SOCKET} is not set`);
     }
+    const relayToken = process.env[ENV_AGENT_HOST_SOCKET_TOKEN]?.trim() ?? "";
     const transport = createGrpcTransport({
-      baseUrl: "http://localhost",
-      nodeOptions: {
-        createConnection: () => connect(socketPath),
-      },
+      ...agentHostTransportOptions(target),
+      interceptors: relayToken ? [agentHostRelayTokenInterceptor(relayToken)] : [],
     });
     this.client = createClient(AgentHostService, transport);
   }
@@ -353,6 +442,68 @@ export class AgentHost {
     return await this.client.executeTool(request);
   }
 
+  async searchTools(
+    request: SearchAgentToolsRequest,
+  ): Promise<SearchAgentToolsResponse> {
+    return await this.client.searchTools(request);
+  }
+
+  async listTools(
+    request: ListAgentToolsRequest,
+  ): Promise<ListAgentToolsResponse> {
+    return await this.client.listTools(request);
+  }
+}
+
+function agentHostTransportOptions(rawTarget: string): {
+  baseUrl: string;
+  nodeOptions?: { path: string };
+} {
+  const target = rawTarget.trim();
+  if (!target) {
+    throw new Error("agent host: transport target is required");
+  }
+  if (target.startsWith("tcp://")) {
+    const address = target.slice("tcp://".length).trim();
+    if (!address) {
+      throw new Error(
+        `agent host: tcp target ${JSON.stringify(rawTarget)} is missing host:port`,
+      );
+    }
+    return { baseUrl: `http://${address}` };
+  }
+  if (target.startsWith("tls://")) {
+    const address = target.slice("tls://".length).trim();
+    if (!address) {
+      throw new Error(
+        `agent host: tls target ${JSON.stringify(rawTarget)} is missing host:port`,
+      );
+    }
+    return { baseUrl: `https://${address}` };
+  }
+  if (target.startsWith("unix://")) {
+    const socketPath = target.slice("unix://".length).trim();
+    if (!socketPath) {
+      throw new Error(
+        `agent host: unix target ${JSON.stringify(rawTarget)} is missing a socket path`,
+      );
+    }
+    return { baseUrl: "http://localhost", nodeOptions: { path: socketPath } };
+  }
+  if (target.includes("://")) {
+    const parsed = new URL(target);
+    throw new Error(
+      `agent host: unsupported target scheme ${JSON.stringify(parsed.protocol.replace(/:$/, ""))}`,
+    );
+  }
+  return { baseUrl: "http://localhost", nodeOptions: { path: target } };
+}
+
+function agentHostRelayTokenInterceptor(token: string): Interceptor {
+  return (next) => async (req) => {
+    req.header.set(AGENT_HOST_RELAY_TOKEN_HEADER, token);
+    return next(req);
+  };
 }
 
 export function createAgentProviderService(
@@ -421,8 +572,10 @@ export function createAgentProviderService(
     },
     async listTurnEvents(request) {
       return create(ListAgentProviderTurnEventsResponseSchema, {
-        events: await invokeAgentProvider("list turn events", () =>
-          provider.listTurnEvents(request),
+        events: normalizeAgentTurnEvents(
+          await invokeAgentProvider("list turn events", () =>
+            provider.listTurnEvents(request),
+          ),
         ),
       });
     },

package/src/api.ts

@@ -35,8 +35,9 @@ export interface Request {
   subject: Subject;
   credential: Credential;
   access: Access;
+  idempotencyKey: string;
   // Workflow callback metadata uses a JSON-style lowerCamelCase object such as
-  // runId, target.pluginName, trigger.scheduleId, and trigger.event.specVersion.
+  // runId, target.plugin.pluginName, trigger.scheduleId, and trigger.event.specVersion.
   workflow: Record<string, unknown>;
   invocationToken: string;
 }
@@ -104,6 +105,7 @@ export function request(
   access: Partial<Access> = {},
   workflow: Record<string, unknown> = {},
   invocationToken = "",
+  idempotencyKey = "",
 ): Request {
   return {
     token,
@@ -130,6 +132,7 @@ export function request(
       ...workflow,
     },
     invocationToken,
+    idempotencyKey: idempotencyKey.trim(),
   };
 }
 

package/src/build.ts

@@ -1,3 +1,5 @@
+#!/usr/bin/env bun
+
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";

package/src/index.ts

@@ -77,21 +77,6 @@ export {
   type CatalogParameter,
   type CatalogSchema,
 } from "./catalog.ts";
-export {
-  hasPluginManifestMetadata,
-  manifestMetadataToYaml,
-  writeManifestMetadataYaml,
-  type HTTPAck,
-  type HTTPAuthScheme,
-  type HTTPBinding,
-  type HTTPIn,
-  type HTTPMediaType,
-  type HTTPRequestBody,
-  type HTTPSecretRef,
-  type HTTPSecurityScheme,
-  type HTTPSecuritySchemeType,
-  type PluginManifestMetadata,
-} from "./manifest-metadata.ts";
 export {
   buildProviderBinary,
   bunBuildCommand,
@@ -143,6 +128,18 @@ export {
   type WorkflowManagerUpdateTriggerInput,
   type WorkflowManagerUpdateScheduleInput,
 } from "./workflow-manager.ts";
+export {
+  ENV_RUNTIME_LOG_HOST_SOCKET,
+  ENV_RUNTIME_LOG_HOST_SOCKET_TOKEN,
+  ENV_RUNTIME_SESSION_ID,
+  RuntimeLogHost,
+  type RuntimeLogAppendInput,
+  type RuntimeLogAppendLogsInput,
+  type RuntimeLogAppendResponseMessage,
+  type RuntimeLogStreamInput,
+  type RuntimeLogStreamName,
+  type RuntimeLogWriterOptions,
+} from "./runtime-log-host.ts";
 export {
   AuthenticationProvider,
   defineAuthenticationProvider,
@@ -199,8 +196,28 @@ export {
   type ProviderKind,
   type ProviderMetadata,
   type RuntimeProviderOptions,
+  type StartHandler,
   type WarningsHandler,
 } from "./provider.ts";
+export {
+  PluginRuntimeEgressMode,
+  PluginRuntimeHostServiceAccess,
+  PluginRuntimeProvider,
+  createPluginRuntimeProviderService,
+  definePluginRuntimeProvider,
+  isPluginRuntimeProvider,
+  type BindPluginRuntimeHostServiceRequest,
+  type GetPluginRuntimeSessionRequest,
+  type HostedPlugin,
+  type ListPluginRuntimeSessionsRequest,
+  type PluginRuntimeHostServiceBinding,
+  type PluginRuntimeProviderOptions,
+  type PluginRuntimeSession,
+  type PluginRuntimeSupport,
+  type StartHostedPluginRequest,
+  type StartPluginRuntimeSessionRequest,
+  type StopPluginRuntimeSessionRequest,
+} from "./pluginruntime.ts";
 export {
   array,
   boolean,
@@ -219,7 +236,6 @@ export {
   ENV_PROVIDER_PARENT_PID,
   ENV_PROVIDER_SOCKET,
   ENV_WRITE_CATALOG,
-  ENV_WRITE_MANIFEST_METADATA,
   createAuthenticationService,
   createCacheService,
   createSecretsService,
@@ -250,15 +266,22 @@ export {
   IndexedDB,
   ObjectStore,
   Index,
+  Transaction,
+  TransactionObjectStore,
+  TransactionIndex,
   Cursor,
   CursorDirection,
   NotFoundError,
   AlreadyExistsError,
+  TransactionError,
   ColumnType,
   indexedDBSocketEnv,
   indexedDBSocketTokenEnv,
   type Record,
   type KeyRange,
+  type TransactionMode,
+  type TransactionDurabilityHint,
+  type TransactionOptions,
   type ColumnSchema,
   type IndexSchema,
   type ObjectStoreSchema,
@@ -283,6 +306,8 @@ export {
   type CopyOptions,
   type ListOptions,
   type ListPage,
+  type ObjectAccessURL,
+  type ObjectAccessURLOptions,
   type ObjectMeta,
   type ObjectRef,
   type PresignOptions,
@@ -296,6 +321,7 @@ export {
 } from "./s3.ts";
 export {
   ENV_AGENT_HOST_SOCKET,
+  ENV_AGENT_HOST_SOCKET_TOKEN,
   AgentHost,
   AgentExecutionStatus,
   AgentInteractionState,
@@ -319,8 +345,11 @@ export {
   type AgentSession,
   type AgentToolRef,
   type AgentTurn,
+  type AgentTurnDisplay,
+  type AgentTurnDisplayInit,
+  type AgentTurnDisplayValue,
   type AgentTurnEvent,
-  type BoundAgentToolTarget,
+  type AgentTurnEventInit,
   type CancelAgentProviderTurnRequest,
   type CreateAgentProviderSessionRequest,
   type CreateAgentProviderTurnRequest,
@@ -330,12 +359,17 @@ export {
   type GetAgentProviderInteractionRequest,
   type GetAgentProviderSessionRequest,
   type GetAgentProviderTurnRequest,
+  type ListAgentToolsRequest,
+  type ListAgentToolsResponse,
   type ListAgentProviderInteractionsRequest,
   type ListAgentProviderSessionsRequest,
   type ListAgentProviderTurnEventsRequest,
   type ListAgentProviderTurnsRequest,
-  type ResolvedAgentTool,
+  type ListedAgentTool,
   type ResolveAgentProviderInteractionRequest,
+  type ResolvedAgentTool,
+  type SearchAgentToolsRequest,
+  type SearchAgentToolsResponse,
   type UpdateAgentProviderSessionRequest,
 } from "./agent.ts";
 export {
@@ -371,3 +405,20 @@ export {
   type WorkflowEvent,
   type WorkflowProviderOptions,
 } from "./workflow.ts";
+export {
+  GENAI_OPERATION_CHAT,
+  GENAI_OPERATION_EXECUTE_TOOL,
+  GENAI_OPERATION_INVOKE_AGENT,
+  GENAI_PROVIDER_NAME,
+  GENAI_TOOL_TYPE_DATASTORE,
+  GENAI_TOOL_TYPE_EXTENSION,
+  GenAIOperation,
+  TELEMETRY_INSTRUMENTATION_NAME,
+  withAgentInvocation,
+  withModelOperation,
+  withToolExecution,
+  type AgentInvocationOptions,
+  type ModelOperationOptions,
+  type TokenUsage,
+  type ToolExecutionOptions,
+} from "./telemetry.ts";