@valon-technologies/gestalt 0.0.1-alpha.18 → 0.0.1-alpha.19

package/README.md

@@ -9,6 +9,21 @@ The package is published as `@valon-technologies/gestalt`.
 bun add @valon-technologies/gestalt@0.0.1-alpha.16
 ```
 
+## API sections
+
+The TypeDoc reference is organized around the provider-authoring workflow. All
+symbols are imported from `@valon-technologies/gestalt` unless the section
+explicitly names a submodule.
+
+| Section | Start with | Use it for |
+| --- | --- | --- |
+| Provider authoring | `definePlugin`, `operation`, `ok` | Executable plugin providers, typed request handlers, and operation results. |
+| Runtime schemas | `s`, `object`, `string` | Runtime validation and generated catalog metadata for operation inputs and outputs. |
+| Provider runtimes | `defineAuthenticationProvider`, `defineCacheProvider`, `defineS3Provider`, `defineWorkflowProvider`, `defineAgentProvider` | Host-service backends implemented as TypeScript providers. |
+| Workflow and agent models | `WorkflowProvider`, `WorkflowManager`, `AgentProvider`, `AgentManager` | Native workflow values, agent sessions, turns, messages, tools, and manager clients. |
+| Host-service clients | `Cache`, `IndexedDB`, `S3`, `PluginInvoker`, `AuthorizationClient` | Calling sibling services exposed to a provider process by `gestaltd`. |
+| Telemetry | `withModelOperation`, `withToolExecution`, `withAgentInvocation` | Provider-authored GenAI spans and metrics inside a running provider process. |
+
 ```ts
 import { definePlugin, ok, operation, s } from "@valon-technologies/gestalt";
 
@@ -62,16 +77,15 @@ is omitted, the runtime looks for `provider`, then `plugin`, then the default
 export.
 
 Use `"plugin"` as the kind token for executable plugin providers. Use an object
-target with an explicit kind for authentication, authorization, cache,
-IndexedDB, S3, secrets, workflow, agent, and hosted-runtime providers.
+target with an explicit kind for authentication, cache, IndexedDB, S3, secrets,
+workflow, agent, and hosted-runtime providers.
 
 ## Public surface
 
 The root package exports provider definition helpers:
 
 - `definePlugin` for integration operations and session catalogs.
-- `defineAuthenticationProvider` and `defineAuthorizationProvider` for auth
-  surfaces.
+- `defineAuthenticationProvider` for authentication surfaces.
 - `defineCacheProvider`, `defineIndexedDBProvider`, `defineS3Provider`, and
   `defineSecretsProvider` for host-service backends.
 - `defineWorkflowProvider`, `defineAgentProvider`, and
@@ -81,6 +95,22 @@ The root package exports provider definition helpers:
 - Host-service clients for cache, IndexedDB, S3, workflows, agents,
   invocations, and telemetry.
 
+`defineAgentProvider` handlers receive and return plain TypeScript objects such
+as `CreateAgentProviderTurnRequest`, `AgentSession`, `AgentTurn`, and
+`AgentTurnEvent`. Structured payload fields accept JSON values and timestamp
+fields use native `Date`; the SDK runtime owns transport serialization at the
+transport boundary. `AgentHost` includes plain-object helpers named
+`listToolsForTurn`, `executeToolForTurn`, and `resolveConnectionForTurn`.
+Workflow helpers such as `boundWorkflowTarget`, `workflowSignal`,
+`boundWorkflowRun`, and `workflowExecutionReference` accept plain JSON objects
+and native `Date` values. Copy helpers such as `boundWorkflowTargetFromTarget`
+preserve request shape without requiring provider code to assemble transport
+objects. Provider-facing APIs should accept native TypeScript values and keep
+transport serialization inside SDK adapters.
+
+The TypeScript SDK does not currently expose an authored authorization-provider
+helper. Use the Go SDK when you need to build a custom authorization provider.
+
 TypeScript types are not enough to describe runtime payloads. Use the schema
 builders for every operation input and output that should appear in the
 Gestalt catalog.
@@ -102,14 +132,6 @@ gestalt-ts-build ROOT plugin:./provider.ts#plugin OUTPUT PROVIDER_NAME GOOS GOAR
 The build entrypoint compiles a standalone executable with Bun and bundles the
 provider source into the result.
 
-## Regenerating protobuf code
-
-From the repo root:
-
-```sh
-buf generate --template sdk/proto/buf.typescript.gen.yaml sdk/proto
-```
-
 ## API reference
 
 The TypeDoc reference is generated from the authored public surface plus

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valon-technologies/gestalt",
-  "version": "0.0.1-alpha.18",
+  "version": "0.0.1-alpha.19",
   "description": "TypeScript SDK for Gestalt executable providers",
   "type": "module",
   "repository": {
@@ -12,6 +12,8 @@
     "./build": "./src/build.ts",
     "./runtime": "./src/runtime.ts",
     "./schema": "./src/schema.ts",
+    "./protocol": "./src/protocol.ts",
+    "./protocol/v1": "./src/protocol/v1.ts",
     "./test/agent-contract": "./src/test-agent-contract.ts",
     "./telemetry": "./src/telemetry.ts",
     "./target": "./src/target.ts"
@@ -31,8 +33,8 @@
   "scripts": {
     "build:proto": "buf generate --template ../proto/buf.typescript.gen.yaml ../proto",
     "docs:lint": "eslint --max-warnings=0 \"src/**/*.ts\" \"docs/entrypoints/**/*.ts\"",
-    "docs:build": "typedoc --options typedoc.json --out docs/_build/html",
-    "docs:build:deploy": "typedoc --options typedoc.json --out ../../docs/public/api/typescript",
+    "docs:build": "typedoc --options typedoc.json --out \"${TYPEDOC_OUT_DIR:-docs/_build/html}\"",
+    "docs:build:deploy": "TYPEDOC_OUT_DIR=../../docs/public/api/typescript bun run docs:build",
     "docs:check": "bun run docs:lint && bun run docs:build",
     "typecheck": "tsc --noEmit",
     "test": "bun test --max-concurrency 1",

package/src/agent-conversions.ts

@@ -0,0 +1,201 @@
+import {
+  create,
+  type MessageInitShape,
+} from "@bufbuild/protobuf";
+
+import {
+  AgentActorSchema,
+  AgentMessagePartSchema,
+  AgentMessagePartType as ProtoAgentMessagePartType,
+  AgentMessageSchema,
+  AgentToolRefSchema,
+  AgentTurnDisplaySchema,
+  type AgentActor as ProtoAgentActor,
+  type AgentMessage as ProtoAgentMessage,
+  type AgentMessagePart as ProtoAgentMessagePart,
+  type AgentToolRef as ProtoAgentToolRef,
+  type AgentTurnDisplay as ProtoAgentTurnDisplay,
+} from "./internal/gen/v1/agent_pb.ts";
+import {
+  jsonFromValue,
+  valueFromJson,
+  type JsonInput,
+} from "./protocol.ts";
+import {
+  optionalObjectFromStruct,
+  optionalStruct,
+} from "./protocol-internal.ts";
+import type {
+  AgentActor,
+  AgentMessage,
+  AgentMessagePart,
+  AgentMessagePartType,
+  AgentToolRef,
+  AgentTurnDisplay,
+} from "./agent.ts";
+
+export function agentTurnDisplayFromProto(
+  display?: ProtoAgentTurnDisplay | undefined,
+): AgentTurnDisplay | undefined {
+  if (display === undefined) {
+    return undefined;
+  }
+  return {
+    kind: display.kind,
+    phase: display.phase,
+    text: display.text,
+    label: display.label,
+    ref: display.ref,
+    parentRef: display.parentRef,
+    input: display.input === undefined ? undefined : jsonFromValue(display.input) as JsonInput,
+    output: display.output === undefined ? undefined : jsonFromValue(display.output) as JsonInput,
+    error: display.error === undefined ? undefined : jsonFromValue(display.error) as JsonInput,
+    action: display.action,
+    format: display.format,
+    language: display.language,
+  };
+}
+
+export function agentTurnDisplayToProto(
+  display: AgentTurnDisplay | undefined,
+): MessageInitShape<typeof AgentTurnDisplaySchema> | undefined {
+  if (!display) {
+    return undefined;
+  }
+  return {
+    kind: display.kind ?? "",
+    phase: display.phase ?? "",
+    text: display.text ?? "",
+    label: display.label ?? "",
+    ref: display.ref ?? "",
+    parentRef: display.parentRef ?? "",
+    input: display.input === undefined ? undefined : valueFromJson(display.input),
+    output: display.output === undefined ? undefined : valueFromJson(display.output),
+    error: display.error === undefined ? undefined : valueFromJson(display.error),
+    action: display.action ?? "",
+    format: display.format ?? "",
+    language: display.language ?? "",
+  };
+}
+
+export function agentMessageFromProto(message: ProtoAgentMessage): AgentMessage {
+  return {
+    role: message.role,
+    text: message.text,
+    parts: message.parts.map(agentMessagePartFromProto),
+    metadata: optionalObjectFromStruct(message.metadata),
+  };
+}
+
+export function agentMessageToProto(
+  message: AgentMessage,
+): MessageInitShape<typeof AgentMessageSchema> {
+  return {
+    role: message.role ?? "",
+    text: message.text ?? "",
+    parts: message.parts?.map(agentMessagePartToProto) ?? [],
+    metadata: optionalStruct(message.metadata),
+  };
+}
+
+export function agentMessagePartFromProto(
+  part: ProtoAgentMessagePart,
+): AgentMessagePart {
+  return {
+    type: part.type as AgentMessagePartType,
+    text: part.text,
+    json: optionalObjectFromStruct(part.json),
+    toolCall: part.toolCall === undefined ? undefined : {
+      id: part.toolCall.id,
+      toolId: part.toolCall.toolId,
+      arguments: optionalObjectFromStruct(part.toolCall.arguments),
+    },
+    toolResult: part.toolResult === undefined ? undefined : {
+      toolCallId: part.toolResult.toolCallId,
+      status: part.toolResult.status,
+      content: part.toolResult.content,
+      output: optionalObjectFromStruct(part.toolResult.output),
+    },
+    imageRef: part.imageRef === undefined ? undefined : {
+      uri: part.imageRef.uri,
+      mimeType: part.imageRef.mimeType,
+    },
+  };
+}
+
+export function agentMessagePartToProto(
+  part: AgentMessagePart,
+): MessageInitShape<typeof AgentMessagePartSchema> {
+  return {
+    type: part.type ?? ProtoAgentMessagePartType.UNSPECIFIED,
+    text: part.text ?? "",
+    json: optionalStruct(part.json),
+    toolCall: part.toolCall === undefined ? undefined : {
+      id: part.toolCall.id ?? "",
+      toolId: part.toolCall.toolId ?? "",
+      arguments: optionalStruct(part.toolCall.arguments),
+    },
+    toolResult: part.toolResult === undefined ? undefined : {
+      toolCallId: part.toolResult.toolCallId ?? "",
+      status: part.toolResult.status ?? 0,
+      content: part.toolResult.content ?? "",
+      output: optionalStruct(part.toolResult.output),
+    },
+    imageRef: part.imageRef === undefined ? undefined : {
+      uri: part.imageRef.uri ?? "",
+      mimeType: part.imageRef.mimeType ?? "",
+    },
+  };
+}
+
+export function agentActorFromProto(
+  actor?: ProtoAgentActor | undefined,
+): AgentActor | undefined {
+  if (actor === undefined) {
+    return undefined;
+  }
+  return {
+    subjectId: actor.subjectId,
+    subjectKind: actor.subjectKind,
+    displayName: actor.displayName,
+    authSource: actor.authSource,
+  };
+}
+
+export function agentActorToProto(
+  actor?: AgentActor | undefined,
+): ProtoAgentActor | undefined {
+  if (actor === undefined) {
+    return undefined;
+  }
+  return create(AgentActorSchema, {
+    subjectId: actor.subjectId ?? "",
+    subjectKind: actor.subjectKind ?? "",
+    displayName: actor.displayName ?? "",
+    authSource: actor.authSource ?? "",
+  });
+}
+
+export function agentToolRefFromProto(ref: ProtoAgentToolRef): AgentToolRef {
+  return {
+    plugin: ref.plugin,
+    operation: ref.operation,
+    connection: ref.connection,
+    instance: ref.instance,
+    title: ref.title,
+    description: ref.description,
+    system: ref.system,
+  };
+}
+
+export function agentToolRefToProto(ref: AgentToolRef): ProtoAgentToolRef {
+  return create(AgentToolRefSchema, {
+    plugin: ref.plugin ?? "",
+    operation: ref.operation ?? "",
+    connection: ref.connection ?? "",
+    instance: ref.instance ?? "",
+    title: ref.title ?? "",
+    description: ref.description ?? "",
+    system: ref.system ?? "",
+  });
+}