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

package/README.md

@@ -19,7 +19,7 @@ explicitly names a submodule.
 | --- | --- | --- |
 | 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. |
+| Provider runtimes | `defineAuthenticationProvider`, `defineAuthorizationProvider`, `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. |
@@ -77,8 +77,8 @@ 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, cache, IndexedDB, S3, secrets,
-workflow, agent, and hosted-runtime providers.
+target with an explicit kind for authentication, authorization, cache,
+IndexedDB, S3, secrets, workflow, agent, and hosted-runtime providers.
 
 ## Public surface
 
@@ -86,6 +86,7 @@ The root package exports provider definition helpers:
 
 - `definePlugin` for integration operations and session catalogs.
 - `defineAuthenticationProvider` for authentication surfaces.
+- `defineAuthorizationProvider` for custom authorization providers.
 - `defineCacheProvider`, `defineIndexedDBProvider`, `defineS3Provider`, and
   `defineSecretsProvider` for host-service backends.
 - `defineWorkflowProvider`, `defineAgentProvider`, and
@@ -108,9 +109,6 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valon-technologies/gestalt",
-  "version": "0.0.1-alpha.19",
+  "version": "0.0.1-alpha.21",
   "description": "TypeScript SDK for Gestalt executable providers",
   "type": "module",
   "repository": {
@@ -12,9 +12,6 @@
     "./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"
   },

package/src/agent-conversions.ts

@@ -8,14 +8,20 @@ import {
   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 {
+  SubjectContextSchema,
+  AgentToolRefSchema,
+  ExternalIdentityContextSchema,
+  type SubjectContext as ProtoSubjectContext,
+  type AgentToolRef as ProtoAgentToolRef,
+  type ExternalIdentityContext as ProtoExternalIdentityContext,
+} from "./internal/gen/v1/plugin_pb.ts";
 import {
   jsonFromValue,
   valueFromJson,
@@ -33,6 +39,7 @@ import type {
   AgentToolRef,
   AgentTurnDisplay,
 } from "./agent.ts";
+import type { ExternalIdentity, Subject, SubjectInput } from "./api.ts";
 
 export function agentTurnDisplayFromProto(
   display?: ProtoAgentTurnDisplay | undefined,
@@ -185,6 +192,8 @@ export function agentToolRefFromProto(ref: ProtoAgentToolRef): AgentToolRef {
     title: ref.title,
     description: ref.description,
     system: ref.system,
+    runAs: agentRunAsSubjectFromProto(ref.runAs),
+    runAsExternalIdentity: externalIdentityFromProto(ref.runAsExternalIdentity),
   };
 }
 
@@ -197,5 +206,63 @@ export function agentToolRefToProto(ref: AgentToolRef): ProtoAgentToolRef {
     title: ref.title ?? "",
     description: ref.description ?? "",
     system: ref.system ?? "",
+    runAs: agentRunAsSubjectToProto(ref.runAs),
+    runAsExternalIdentity: externalIdentityToProto(ref.runAsExternalIdentity),
+  });
+}
+
+function agentRunAsSubjectFromProto(
+  subject?: ProtoSubjectContext | undefined,
+): Subject | undefined {
+  if (subject === undefined) {
+    return undefined;
+  }
+  return {
+    id: subject.id,
+    kind: subject.kind,
+    credentialSubjectId: subject.credentialSubjectId,
+    displayName: subject.displayName,
+    authSource: subject.authSource,
+    email: subject.email,
+  };
+}
+
+function agentRunAsSubjectToProto(
+  subject?: SubjectInput | undefined,
+): ProtoSubjectContext | undefined {
+  if (subject === undefined) {
+    return undefined;
+  }
+  return create(SubjectContextSchema, {
+    id: subject.id ?? "",
+    kind: subject.kind ?? "",
+    credentialSubjectId: subject.credentialSubjectId ?? "",
+    displayName: subject.displayName ?? "",
+    authSource: subject.authSource ?? "",
+    email: subject.email ?? "",
+  });
+}
+
+function externalIdentityFromProto(
+  identity?: ProtoExternalIdentityContext | undefined,
+): ExternalIdentity | undefined {
+  if (identity === undefined) {
+    return undefined;
+  }
+  return {
+    type: identity.type,
+    id: identity.id,
+  };
+}
+
+function externalIdentityToProto(
+  identity?: ExternalIdentity | undefined,
+): ProtoExternalIdentityContext | undefined {
+  if (identity === undefined) {
+    return undefined;
+  }
+  return create(ExternalIdentityContextSchema, {
+    type: identity.type,
+    id: identity.id,
   });
 }

package/src/agent-manager.ts

@@ -61,7 +61,7 @@ export interface AgentManagerWorkspace {
 }
 
 /** Shape accepted when creating an agent session through the host manager. */
-export interface AgentManagerCreateSessionInput {
+export interface AgentManagerCreateSession {
   providerName: string;
   model?: string | undefined;
   clientRef?: string | undefined;
@@ -71,12 +71,12 @@ export interface AgentManagerCreateSessionInput {
 }
 
 /** Shape accepted when fetching an agent session through the host manager. */
-export interface AgentManagerGetSessionInput {
+export interface AgentManagerGetSession {
   sessionId: string;
 }
 
 /** Shape accepted when listing agent sessions through the host manager. */
-export interface AgentManagerListSessionsInput {
+export interface AgentManagerListSessions {
   providerName?: string | undefined;
   state?: AgentSessionState | undefined;
   limit?: number | undefined;
@@ -84,7 +84,7 @@ export interface AgentManagerListSessionsInput {
 }
 
 /** Shape accepted when updating an agent session through the host manager. */
-export interface AgentManagerUpdateSessionInput {
+export interface AgentManagerUpdateSession {
   sessionId: string;
   clientRef?: string | undefined;
   state?: AgentSessionState | undefined;
@@ -92,25 +92,27 @@ export interface AgentManagerUpdateSessionInput {
 }
 
 /** Shape accepted when creating an agent turn through the host manager. */
-export interface AgentManagerCreateTurnInput {
+export interface AgentManagerCreateTurn {
   sessionId: string;
   model?: string | undefined;
   messages?: readonly AgentMessage[] | undefined;
   toolRefs?: readonly AgentToolRef[] | undefined;
+  toolRefsSet?: boolean | undefined;
   toolSource?: AgentToolSourceMode | undefined;
   responseSchema?: JsonObjectInput | undefined;
   metadata?: JsonObjectInput | undefined;
   idempotencyKey?: string | undefined;
   modelOptions?: JsonObjectInput | undefined;
+  timeoutSeconds?: number | undefined;
 }
 
 /** Shape accepted when fetching an agent turn through the host manager. */
-export interface AgentManagerGetTurnInput {
+export interface AgentManagerGetTurn {
   turnId: string;
 }
 
 /** Shape accepted when listing agent turns through the host manager. */
-export interface AgentManagerListTurnsInput {
+export interface AgentManagerListTurns {
   sessionId: string;
   status?: AgentExecutionStatus | undefined;
   limit?: number | undefined;
@@ -118,25 +120,25 @@ export interface AgentManagerListTurnsInput {
 }
 
 /** Shape accepted when cancelling an agent turn through the host manager. */
-export interface AgentManagerCancelTurnInput {
+export interface AgentManagerCancelTurn {
   turnId: string;
   reason?: string | undefined;
 }
 
 /** Shape accepted when listing events for an agent turn. */
-export interface AgentManagerListTurnEventsInput {
+export interface AgentManagerListTurnEvents {
   turnId: string;
   afterSeq?: bigint | number | undefined;
   limit?: number | undefined;
 }
 
 /** Shape accepted when listing agent interactions. */
-export interface AgentManagerListInteractionsInput {
+export interface AgentManagerListInteractions {
   turnId: string;
 }
 
 /** Shape accepted when resolving an agent interaction. */
-export interface AgentManagerResolveInteractionInput {
+export interface AgentManagerResolveInteraction {
   turnId: string;
   interactionId: string;
   resolution?: JsonObjectInput | undefined;
@@ -175,7 +177,7 @@ export class AgentManager {
 
   /** Creates an agent session. */
   async createSession(
-    request: AgentManagerCreateSessionInput,
+    request: AgentManagerCreateSession,
   ): Promise<AgentSession> {
     return agentSessionFromProto(
       await this.client.createSession({
@@ -191,7 +193,7 @@ export class AgentManager {
   }
 
   /** Fetches one agent session. */
-  async getSession(request: AgentManagerGetSessionInput): Promise<AgentSession> {
+  async getSession(request: AgentManagerGetSession): Promise<AgentSession> {
     return agentSessionFromProto(
       await this.client.getSession({
         sessionId: request.sessionId,
@@ -202,7 +204,7 @@ export class AgentManager {
 
   /** Lists agent sessions visible to the invocation token. */
   async listSessions(
-    request: AgentManagerListSessionsInput = {},
+    request: AgentManagerListSessions = {},
   ): Promise<AgentSession[]> {
     const response = await this.client.listSessions({
       providerName: request.providerName ?? "",
@@ -216,7 +218,7 @@ export class AgentManager {
 
   /** Updates mutable fields on an agent session. */
   async updateSession(
-    request: AgentManagerUpdateSessionInput,
+    request: AgentManagerUpdateSession,
   ): Promise<AgentSession> {
     return agentSessionFromProto(
       await this.client.updateSession({
@@ -230,25 +232,27 @@ export class AgentManager {
   }
 
   /** Creates an agent turn. */
-  async createTurn(request: AgentManagerCreateTurnInput): Promise<AgentTurn> {
+  async createTurn(request: AgentManagerCreateTurn): Promise<AgentTurn> {
     return agentTurnFromProto(
       await this.client.createTurn({
         sessionId: request.sessionId,
         model: request.model ?? "",
         messages: request.messages?.map(agentMessageToProto) ?? [],
         toolRefs: request.toolRefs?.map(agentToolRefToProto) ?? [],
+        toolRefsSet: request.toolRefsSet ?? (request.toolRefs !== undefined && request.toolRefs.length > 0),
         toolSource: request.toolSource ?? AgentToolSourceMode.UNSPECIFIED,
         responseSchema: optionalStruct(request.responseSchema),
         metadata: optionalStruct(request.metadata),
         idempotencyKey: request.idempotencyKey ?? "",
         invocationToken: this.invocationToken,
         modelOptions: optionalStruct(request.modelOptions),
+        timeoutSeconds: request.timeoutSeconds ?? 0,
       }),
     );
   }
 
   /** Fetches one agent turn. */
-  async getTurn(request: AgentManagerGetTurnInput): Promise<AgentTurn> {
+  async getTurn(request: AgentManagerGetTurn): Promise<AgentTurn> {
     return agentTurnFromProto(
       await this.client.getTurn({
         turnId: request.turnId,
@@ -258,7 +262,7 @@ export class AgentManager {
   }
 
   /** Lists turns for an agent session. */
-  async listTurns(request: AgentManagerListTurnsInput): Promise<AgentTurn[]> {
+  async listTurns(request: AgentManagerListTurns): Promise<AgentTurn[]> {
     const response = await this.client.listTurns({
       sessionId: request.sessionId,
       invocationToken: this.invocationToken,
@@ -270,7 +274,7 @@ export class AgentManager {
   }
 
   /** Cancels an in-progress agent turn. */
-  async cancelTurn(request: AgentManagerCancelTurnInput): Promise<AgentTurn> {
+  async cancelTurn(request: AgentManagerCancelTurn): Promise<AgentTurn> {
     return agentTurnFromProto(
       await this.client.cancelTurn({
         turnId: request.turnId,
@@ -282,7 +286,7 @@ export class AgentManager {
 
   /** Lists events emitted for an agent turn. */
   async listTurnEvents(
-    request: AgentManagerListTurnEventsInput,
+    request: AgentManagerListTurnEvents,
   ): Promise<AgentTurnEvent[]> {
     const response = await this.client.listTurnEvents({
       turnId: request.turnId,
@@ -295,7 +299,7 @@ export class AgentManager {
 
   /** Lists pending or completed agent interactions. */
   async listInteractions(
-    request: AgentManagerListInteractionsInput,
+    request: AgentManagerListInteractions,
   ): Promise<AgentInteraction[]> {
     const response = await this.client.listInteractions({
       turnId: request.turnId,
@@ -306,7 +310,7 @@ export class AgentManager {
 
   /** Resolves an agent interaction with a host response. */
   async resolveInteraction(
-    request: AgentManagerResolveInteractionInput,
+    request: AgentManagerResolveInteraction,
   ): Promise<AgentInteraction> {
     return agentInteractionFromProto(
       await this.client.resolveInteraction({

package/src/agent.ts

@@ -40,8 +40,6 @@ import {
   type AgentMessagePartToolCall as ProtoAgentMessagePartToolCall,
   type AgentMessagePartToolResult as ProtoAgentMessagePartToolResult,
   type AgentSession as ProtoAgentSession,
-  type AgentSubjectContext as ProtoAgentSubjectContext,
-  type AgentToolRef as ProtoAgentToolRef,
   type AgentTurn as ProtoAgentTurn,
   type AgentTurnEvent as ProtoAgentTurnEvent,
   type CancelAgentProviderTurnRequest as ProtoCancelAgentProviderTurnRequest,
@@ -66,7 +64,17 @@ import {
   type ResolvedAgentTool as ProtoResolvedAgentTool,
   type UpdateAgentProviderSessionRequest as ProtoUpdateAgentProviderSessionRequest,
 } from "./internal/gen/v1/agent_pb.ts";
-import { errorMessage, type MaybePromise } from "./api.ts";
+import {
+  type SubjectContext as ProtoSubjectContext,
+  type AgentToolRef as ProtoAgentToolRef,
+} from "./internal/gen/v1/plugin_pb.ts";
+import {
+  errorMessage,
+  type ExternalIdentity,
+  type MaybePromise,
+  type Subject,
+  type SubjectInput,
+} from "./api.ts";
 import {
   agentActorFromProto,
   agentActorToProto,
@@ -109,6 +117,7 @@ export type AgentMessagePartType =
 export const AgentToolSourceMode = {
   UNSPECIFIED: ProtoAgentToolSourceMode.UNSPECIFIED,
   MCP_CATALOG: ProtoAgentToolSourceMode.MCP_CATALOG,
+  NONE: ProtoAgentToolSourceMode.NONE,
 } as const;
 export type AgentToolSourceMode =
   (typeof AgentToolSourceMode)[keyof typeof AgentToolSourceMode];
@@ -196,14 +205,6 @@ export interface AgentActor {
   authSource?: string | undefined;
 }
 
-export interface AgentSubjectContext {
-  subjectId?: string | undefined;
-  subjectKind?: string | undefined;
-  credentialSubjectId?: string | undefined;
-  displayName?: string | undefined;
-  authSource?: string | undefined;
-}
-
 export interface AgentToolRef {
   plugin?: string | undefined;
   operation?: string | undefined;
@@ -212,6 +213,8 @@ export interface AgentToolRef {
   title?: string | undefined;
   description?: string | undefined;
   system?: string | undefined;
+  runAs?: SubjectInput | undefined;
+  runAsExternalIdentity?: ExternalIdentity | undefined;
 }
 
 export interface ResolvedAgentTool {
@@ -279,18 +282,18 @@ export interface CreateAgentProviderSessionRequest {
   clientRef: string;
   metadata?: JsonObjectInput | undefined;
   createdBy?: AgentActor | undefined;
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
   sessionStart?: AgentSessionStartConfig | undefined;
   preparedWorkspace?: AgentPreparedWorkspace | undefined;
 }
 
 export interface GetAgentProviderSessionRequest {
   sessionId: string;
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
 }
 
 export interface ListAgentProviderSessionsRequest {
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
   sessionIds: readonly string[];
   state: AgentSessionState;
   limit: number;
@@ -306,7 +309,7 @@ export interface UpdateAgentProviderSessionRequest {
   clientRef: string;
   state: AgentSessionState;
   metadata?: JsonObjectInput | undefined;
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
 }
 
 export interface AgentTurn {
@@ -354,19 +357,20 @@ export interface CreateAgentProviderTurnRequest {
   executionRef: string;
   toolRefs: readonly AgentToolRef[];
   toolSource: AgentToolSourceMode;
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
   modelOptions?: JsonObjectInput | undefined;
   runGrant: string;
+  timeoutSeconds: number;
 }
 
 export interface GetAgentProviderTurnRequest {
   turnId: string;
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
 }
 
 export interface ListAgentProviderTurnsRequest {
   sessionId: string;
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
   turnIds: readonly string[];
   status: AgentExecutionStatus;
   limit: number;
@@ -380,7 +384,7 @@ export interface ListAgentProviderTurnsResponse {
 export interface CancelAgentProviderTurnRequest {
   turnId: string;
   reason: string;
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
 }
 
 export interface AgentTurnEvent {
@@ -399,7 +403,7 @@ export interface ListAgentProviderTurnEventsRequest {
   turnId: string;
   afterSeq: bigint;
   limit: number;
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
 }
 
 export interface ListAgentProviderTurnEventsResponse {
@@ -422,12 +426,12 @@ export interface AgentInteraction {
 
 export interface GetAgentProviderInteractionRequest {
   interactionId: string;
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
 }
 
 export interface ListAgentProviderInteractionsRequest {
   turnId: string;
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
 }
 
 export interface ListAgentProviderInteractionsResponse {
@@ -437,7 +441,7 @@ export interface ListAgentProviderInteractionsResponse {
 export interface ResolveAgentProviderInteractionRequest {
   interactionId: string;
   resolution?: JsonObjectInput | undefined;
-  subject?: AgentSubjectContext | undefined;
+  subject?: Subject | undefined;
 }
 
 export interface GetAgentProviderCapabilitiesRequest {}
@@ -836,6 +840,7 @@ function createAgentProviderTurnRequestFromProto(
     subject: agentSubjectFromProto(request.subject),
     modelOptions: optionalObjectFromStruct(request.modelOptions),
     runGrant: request.runGrant,
+    timeoutSeconds: request.timeoutSeconds,
   };
 }
 
@@ -1008,17 +1013,18 @@ function resolvedAgentToolFromProto(tool: ProtoResolvedAgentTool): ResolvedAgent
 }
 
 function agentSubjectFromProto(
-  subject?: ProtoAgentSubjectContext | undefined,
-): AgentSubjectContext | undefined {
+  subject?: ProtoSubjectContext | undefined,
+): Subject | undefined {
   if (subject === undefined) {
     return undefined;
   }
   return {
-    subjectId: subject.subjectId,
-    subjectKind: subject.subjectKind,
+    id: subject.id,
+    kind: subject.kind,
     credentialSubjectId: subject.credentialSubjectId,
     displayName: subject.displayName,
     authSource: subject.authSource,
+    email: subject.email,
   };
 }
 

package/src/api.ts

@@ -1,9 +1,12 @@
 /**
  * Common request and response types shared across authored Gestalt providers.
  */
+import type { AgentToolRef } from "./agent.ts";
+
 export interface Subject {
   id: string;
   kind: string;
+  credentialSubjectId: string;
   displayName: string;
   authSource: string;
   email: string;
@@ -15,6 +18,7 @@ export interface Subject {
 export interface SubjectInput {
   id: string;
   kind: string;
+  credentialSubjectId?: string | undefined;
   displayName: string;
   authSource: string;
   email?: string | undefined;
@@ -70,6 +74,8 @@ export interface Request {
   // Workflow callback metadata uses a JSON-style lowerCamelCase object such as
   // runId, target.plugin.pluginName, trigger.scheduleId, and trigger.event.specVersion.
   workflow: Record<string, unknown>;
+  toolRefs: AgentToolRef[];
+  toolRefsSet: boolean;
   invocationToken: string;
 }
 
@@ -141,6 +147,8 @@ export function request(
   agentSubject: Partial<Subject> = {},
   externalIdentity: Partial<ExternalIdentity> = {},
   agentExternalIdentity: Partial<ExternalIdentity> = {},
+  toolRefs: readonly AgentToolRef[] = [],
+  toolRefsSet = false,
 ): Request {
   return {
     token,
@@ -150,6 +158,7 @@ export function request(
     subject: {
       id: subject.id ?? "",
       kind: subject.kind ?? "",
+      credentialSubjectId: subject.credentialSubjectId ?? "",
       displayName: subject.displayName ?? "",
       authSource: subject.authSource ?? "",
       email: subject.email ?? "",
@@ -157,6 +166,7 @@ export function request(
     agentSubject: {
       id: agentSubject.id ?? "",
       kind: agentSubject.kind ?? "",
+      credentialSubjectId: agentSubject.credentialSubjectId ?? "",
       displayName: agentSubject.displayName ?? "",
       authSource: agentSubject.authSource ?? "",
       email: agentSubject.email ?? "",
@@ -182,6 +192,15 @@ export function request(
     workflow: {
       ...workflow,
     },
+    toolRefs: toolRefs.map((ref) => ({
+      ...ref,
+      runAs: ref.runAs === undefined ? undefined : { ...ref.runAs },
+      runAsExternalIdentity:
+        ref.runAsExternalIdentity === undefined
+          ? undefined
+          : { ...ref.runAsExternalIdentity },
+    })),
+    toolRefsSet,
     host: {
       publicBaseUrl: host.publicBaseUrl ?? "",
     },