@valon-technologies/gestalt 0.0.1-alpha.32 → 0.0.1-alpha.34

package/README.md

@@ -19,9 +19,9 @@ explicitly names a submodule.
 | --- | --- | --- |
 | Provider authoring | `defineApp`, `operation`, `ok` | Executable app 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`, `defineAuthorizationProvider`, `defineCacheProvider`, `defineS3Provider`, `defineWorkflowProvider`, `defineAgentProvider` | Host-service backends implemented as TypeScript providers. |
+| Provider runtimes | `defineAuthenticationProvider`, `defineCacheProvider`, `defineS3Provider`, `defineWorkflowProvider`, `defineAgentProvider` | Host-service backends implemented as TypeScript providers. |
 | Workflow and agent models | `WorkflowProvider`, `Workflow`, `AgentProvider`, `Agent` | Native workflow values, agent sessions, turns, messages, tools, and host-service access. |
-| Host-service clients | `Cache`, `IndexedDB`, `S3`, `App`, `Authorization` | Calling sibling services exposed to a provider process by `gestaltd`. |
+| Host-service clients | `Cache`, `IndexedDB`, `S3`, `App` | 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
@@ -77,8 +77,8 @@ is omitted, the runtime looks for `provider`, then `app`, then the default
 export.
 
 Use `"app"` as the kind token for executable app 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
 
@@ -86,7 +86,6 @@ The root package exports provider definition helpers:
 
 - `defineApp` 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valon-technologies/gestalt",
-  "version": "0.0.1-alpha.32",
+  "version": "0.0.1-alpha.34",
   "description": "TypeScript SDK for Gestalt executable providers",
   "type": "module",
   "repository": {

package/src/agent-access.ts

@@ -12,7 +12,6 @@ import {
 } from "./internal/gen/v1/agent_pb.ts";
 import type { Request } from "./api.ts";
 import {
-  agentActorFromProto,
   agentOutputToProto,
   agentMessageFromProto,
   agentMessageToProto,
@@ -38,6 +37,7 @@ import {
   dateFromTimestamp,
   type JsonObjectInput,
 } from "./protocol.ts";
+import { hostInvocationContext } from "./invocation-context.ts";
 import {
   optionalObjectFromStruct,
   optionalStruct,
@@ -171,12 +171,12 @@ export interface Agent {
  */
 class AgentImpl implements Agent {
   private readonly client: Client<typeof AgentProviderService>;
-  private readonly invocationToken: string;
+  private readonly invocationContext: ReturnType<typeof hostInvocationContext>;
 
   constructor(request: Request);
   constructor(invocationToken: string);
   constructor(requestOrToken: Request | string) {
-    this.invocationToken = normalizeInvocationToken(requestOrToken);
+    this.invocationContext = hostInvocationContext(requestOrToken);
 
     const target = process.env[ENV_HOST_SERVICE_SOCKET]?.trim();
     if (!target) {
@@ -203,7 +203,7 @@ class AgentImpl implements Agent {
         clientRef: request.clientRef ?? "",
         metadata: optionalStruct(request.metadata),
         idempotencyKey: request.idempotencyKey ?? "",
-        invocationToken: this.invocationToken,
+        ...this.invocationContext,
         workspace: workspaceToProto(request.workspace),
       }),
     );
@@ -214,7 +214,7 @@ class AgentImpl implements Agent {
     return agentSessionFromProto(
       await this.client.getSession({
         sessionId: request.sessionId,
-        invocationToken: this.invocationToken,
+        ...this.invocationContext,
       }),
     );
   }
@@ -225,7 +225,7 @@ class AgentImpl implements Agent {
   ): Promise<AgentSession[]> {
     const response = await this.client.listSessions({
       providerName: request.providerName ?? "",
-      invocationToken: this.invocationToken,
+      ...this.invocationContext,
       state: request.state ?? AgentSessionState.UNSPECIFIED,
       limit: request.limit ?? 0,
       summaryOnly: request.summaryOnly ?? false,
@@ -243,13 +243,17 @@ class AgentImpl implements Agent {
         clientRef: request.clientRef ?? "",
         state: request.state ?? AgentSessionState.UNSPECIFIED,
         metadata: optionalStruct(request.metadata),
-        invocationToken: this.invocationToken,
+        ...this.invocationContext,
       }),
     );
   }
 
   /** Creates an agent turn. */
   async createTurn(request: AgentCreateTurn): Promise<AgentTurn> {
+    const timeoutSeconds = request.timeoutSeconds ?? 0;
+    if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 0) {
+      throw new Error("agent create turn timeoutSeconds must not be negative");
+    }
     return agentTurnFromProto(
       await this.client.createTurn({
         sessionId: request.sessionId,
@@ -260,9 +264,9 @@ class AgentImpl implements Agent {
         output: agentOutputToProto(request.output),
         metadata: optionalStruct(request.metadata),
         idempotencyKey: request.idempotencyKey ?? "",
-        invocationToken: this.invocationToken,
+        ...this.invocationContext,
         modelOptions: optionalStruct(request.modelOptions),
-        timeoutSeconds: request.timeoutSeconds ?? 0,
+        timeoutSeconds,
       }),
     );
   }
@@ -272,7 +276,7 @@ class AgentImpl implements Agent {
     return agentTurnFromProto(
       await this.client.getTurn({
         turnId: request.turnId,
-        invocationToken: this.invocationToken,
+        ...this.invocationContext,
       }),
     );
   }
@@ -281,7 +285,7 @@ class AgentImpl implements Agent {
   async listTurns(request: AgentListTurns): Promise<AgentTurn[]> {
     const response = await this.client.listTurns({
       sessionId: request.sessionId,
-      invocationToken: this.invocationToken,
+      ...this.invocationContext,
       status: request.status ?? AgentExecutionStatus.UNSPECIFIED,
       limit: request.limit ?? 0,
       summaryOnly: request.summaryOnly ?? false,
@@ -295,7 +299,7 @@ class AgentImpl implements Agent {
       await this.client.cancelTurn({
         turnId: request.turnId,
         reason: request.reason ?? "",
-        invocationToken: this.invocationToken,
+        ...this.invocationContext,
       }),
     );
   }
@@ -308,7 +312,7 @@ class AgentImpl implements Agent {
       turnId: request.turnId,
       afterSeq: BigInt(request.afterSeq ?? 0),
       limit: request.limit ?? 0,
-      invocationToken: this.invocationToken,
+      ...this.invocationContext,
     });
     return response.events.map(agentTurnEventFromProto);
   }
@@ -319,7 +323,7 @@ class AgentImpl implements Agent {
   ): Promise<AgentInteraction[]> {
     const response = await this.client.listInteractions({
       turnId: request.turnId,
-      invocationToken: this.invocationToken,
+      ...this.invocationContext,
     });
     return response.interactions.map(agentInteractionFromProto);
   }
@@ -333,24 +337,12 @@ class AgentImpl implements Agent {
         turnId: request.turnId,
         interactionId: request.interactionId,
         resolution: optionalStruct(request.resolution),
-        invocationToken: this.invocationToken,
+        ...this.invocationContext,
       }),
     );
   }
 }
 
-function normalizeInvocationToken(requestOrToken: Request | string): string {
-  const invocationToken =
-    typeof requestOrToken === "string"
-      ? requestOrToken
-      : requestOrToken.invocationToken;
-  const trimmed = invocationToken.trim();
-  if (!trimmed) {
-    throw new Error("agent: invocation token is not available");
-  }
-  return trimmed;
-}
-
 function workspaceToProto(workspace?: AgentWorkspace | undefined) {
   if (workspace === undefined) {
     return undefined;
@@ -375,7 +367,7 @@ function agentSessionFromProto(session: ProtoAgentSession): AgentSession {
     clientRef: session.clientRef,
     state: session.state as AgentSessionState,
     metadata: optionalObjectFromStruct(session.metadata),
-    createdBy: agentActorFromProto(session.createdBy),
+    createdBySubjectId: session.createdBySubjectId ?? "",
     createdAt: optionalDate(session.createdAt),
     updatedAt: optionalDate(session.updatedAt),
     lastTurnAt: optionalDate(session.lastTurnAt),
@@ -392,7 +384,7 @@ function agentTurnFromProto(turn: ProtoAgentTurn): AgentTurn {
     messages: turn.messages.map(agentMessageFromProto),
     output: agentTurnOutputFromProto(turn.output),
     statusMessage: turn.statusMessage,
-    createdBy: agentActorFromProto(turn.createdBy),
+    createdBySubjectId: turn.createdBySubjectId ?? "",
     createdAt: optionalDate(turn.createdAt),
     startedAt: optionalDate(turn.startedAt),
     completedAt: optionalDate(turn.completedAt),

package/src/agent-conversions.ts

@@ -4,7 +4,6 @@ import {
 } from "@bufbuild/protobuf";
 
 import {
-  AgentActorSchema,
   AgentOutputSchema,
   AgentStructuredOutputSchema,
   AgentTextOutputSchema,
@@ -14,7 +13,6 @@ import {
   AgentTurnDisplaySchema,
   AgentTurnStructuredOutputSchema,
   AgentTurnTextOutputSchema,
-  type AgentActor as ProtoAgentActor,
   type AgentMessage as ProtoAgentMessage,
   type AgentMessagePart as ProtoAgentMessagePart,
   type AgentOutput as ProtoAgentOutput,
@@ -37,7 +35,6 @@ import {
   optionalStruct,
 } from "./protocol-internal.ts";
 import type {
-  AgentActor,
   AgentOutput,
   AgentMessage,
   AgentMessagePart,
@@ -266,34 +263,6 @@ export function agentMessagePartToProto(
   };
 }
 
-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 {
     app: ref.app,
@@ -328,10 +297,7 @@ function agentRunAsSubjectFromProto(
   }
   return {
     id: subject.id,
-    kind: subject.kind,
     credentialSubjectId: subject.credentialSubjectId,
-    displayName: subject.displayName,
-    authSource: subject.authSource,
     email: subject.email,
   };
 }
@@ -344,10 +310,7 @@ function agentRunAsSubjectToProto(
   }
   return create(SubjectContextSchema, {
     id: subject.id ?? "",
-    kind: subject.kind ?? "",
     credentialSubjectId: subject.credentialSubjectId ?? "",
-    displayName: subject.displayName ?? "",
-    authSource: subject.authSource ?? "",
     email: subject.email ?? "",
   });
 }

package/src/agent.ts

@@ -39,7 +39,6 @@ import {
   ListAgentProviderTurnEventsResponseSchema,
   ListAgentProviderTurnsResponseSchema,
   ResolveAgentConnectionRequestSchema,
-  type AgentActor as ProtoAgentActor,
   type AgentInteraction as ProtoAgentInteraction,
   type AgentMessagePartImageRef as ProtoAgentMessagePartImageRef,
   type AgentMessagePartToolCall as ProtoAgentMessagePartToolCall,
@@ -80,8 +79,6 @@ import {
   type SubjectInput,
 } from "./api.ts";
 import {
-  agentActorFromProto,
-  agentActorToProto,
   agentOutputFromProto,
   agentOutputToProto,
   agentMessageFromProto,
@@ -200,12 +197,6 @@ export interface AgentMessage {
   metadata?: JsonObjectInput | undefined;
 }
 
-export interface AgentActor {
-  subjectId?: string | undefined;
-  subjectKind?: string | undefined;
-  displayName?: string | undefined;
-  authSource?: string | undefined;
-}
 
 export interface AgentToolRef {
   app?: string | undefined;
@@ -245,7 +236,7 @@ export interface AgentSession {
   clientRef?: string | undefined;
   state?: AgentSessionState | undefined;
   metadata?: JsonObjectInput | undefined;
-  createdBy?: AgentActor | undefined;
+  createdBySubjectId?: string | undefined;
   createdAt?: Date | undefined;
   updatedAt?: Date | undefined;
   lastTurnAt?: Date | undefined;
@@ -281,7 +272,7 @@ export interface CreateAgentProviderSessionRequest {
   model: string;
   clientRef: string;
   metadata?: JsonObjectInput | undefined;
-  createdBy?: AgentActor | undefined;
+  createdBySubjectId?: string | undefined;
   subject?: Subject | undefined;
   sessionStart?: AgentSessionStartConfig | undefined;
   preparedWorkspace?: AgentPreparedWorkspace | undefined;
@@ -325,7 +316,7 @@ export interface AgentTurn {
   messages?: readonly AgentMessage[] | undefined;
   output?: AgentTurnOutput | undefined;
   statusMessage?: string | undefined;
-  createdBy?: AgentActor | undefined;
+  createdBySubjectId?: string | undefined;
   createdAt?: Date | undefined;
   startedAt?: Date | undefined;
   completedAt?: Date | undefined;
@@ -365,7 +356,7 @@ export interface CreateAgentProviderTurnRequest {
   tools: readonly ResolvedAgentTool[];
   output: AgentOutput;
   metadata?: JsonObjectInput | undefined;
-  createdBy?: AgentActor | undefined;
+  createdBySubjectId?: string | undefined;
   executionRef: string;
   toolRefs: readonly AgentToolRef[];
   toolSource: AgentToolSourceMode;
@@ -816,7 +807,7 @@ function createAgentProviderSessionRequestFromProto(
     model: request.model,
     clientRef: request.clientRef,
     metadata: optionalObjectFromStruct(request.metadata),
-    createdBy: agentActorFromProto(request.createdBy),
+    createdBySubjectId: request.createdBySubjectId ?? "",
     subject: agentSubjectFromProto(request.subject),
     sessionStart: request.sessionStart === undefined ? undefined : {
       hooks: request.sessionStart.hooks.map((hook) => ({
@@ -888,6 +879,12 @@ function createAgentProviderTurnRequestFromProto(
   if (output === undefined) {
     throw new ConnectError("create turn output is required", Code.InvalidArgument);
   }
+  if (!Number.isInteger(request.timeoutSeconds) || request.timeoutSeconds < 0) {
+    throw new ConnectError(
+      "agent create turn timeoutSeconds must not be negative",
+      Code.InvalidArgument,
+    );
+  }
   return {
     turnId: request.turnId,
     sessionId: request.sessionId,
@@ -897,7 +894,7 @@ function createAgentProviderTurnRequestFromProto(
     tools: request.tools.map(resolvedAgentToolFromProto),
     output,
     metadata: optionalObjectFromStruct(request.metadata),
-    createdBy: agentActorFromProto(request.createdBy),
+    createdBySubjectId: request.createdBySubjectId ?? "",
     executionRef: request.executionRef,
     toolRefs: request.toolRefs.map(agentToolRefFromProto),
     toolSource: request.toolSource as AgentToolSourceMode,
@@ -997,7 +994,7 @@ function agentSessionToProto(
     clientRef: session.clientRef ?? "",
     state: session.state ?? AgentSessionState.UNSPECIFIED,
     metadata: optionalStruct(session.metadata),
-    createdBy: agentActorToProto(session.createdBy),
+    createdBySubjectId: session.createdBySubjectId ?? "",
     createdAt: optionalTimestamp(session.createdAt),
     updatedAt: optionalTimestamp(session.updatedAt),
     lastTurnAt: optionalTimestamp(session.lastTurnAt),
@@ -1014,7 +1011,7 @@ function agentTurnToProto(turn: AgentTurn): MessageInitShape<typeof AgentTurnSch
     messages: turn.messages?.map(agentMessageToProto) ?? [],
     output: agentTurnOutputToProto(turn.output),
     statusMessage: turn.statusMessage ?? "",
-    createdBy: agentActorToProto(turn.createdBy),
+    createdBySubjectId: turn.createdBySubjectId ?? "",
     createdAt: optionalTimestamp(turn.createdAt),
     startedAt: optionalTimestamp(turn.startedAt),
     completedAt: optionalTimestamp(turn.completedAt),
@@ -1090,10 +1087,7 @@ function agentSubjectFromProto(
   }
   return {
     id: subject.id,
-    kind: subject.kind,
     credentialSubjectId: subject.credentialSubjectId,
-    displayName: subject.displayName,
-    authSource: subject.authSource,
     email: subject.email,
   };
 }

package/src/api.ts

@@ -5,10 +5,7 @@ import type { AgentToolRef } from "./agent.ts";
 
 export interface Subject {
   id: string;
-  kind: string;
   credentialSubjectId: string;
-  displayName: string;
-  authSource: string;
   email: string;
 }
 
@@ -17,10 +14,7 @@ export interface Subject {
  */
 export interface SubjectInput {
   id: string;
-  kind: string;
   credentialSubjectId?: string | undefined;
-  displayName: string;
-  authSource: string;
   email?: string | undefined;
 }
 
@@ -62,7 +56,7 @@ export interface Request {
   host: Host;
   idempotencyKey: string;
   // Workflow callback metadata uses a JSON-style lowerCamelCase object such as
-  // runId, target.steps, trigger.scheduleId, and trigger.event.specVersion.
+  // runId, target.steps, trigger.activationId, and trigger.event.specVersion.
   workflow: Record<string, unknown>;
   toolRefs: AgentToolRef[];
   toolRefsSet: boolean;
@@ -136,6 +130,22 @@ export function ok<T>(body: T, headers?: ResponseHeaders): Response<T> {
  * const input = request("token", { region: "us-east-1" }, { id: "usr_123" });
  * ```
  */
+export function parseSubjectId(
+  subjectId: string,
+): { kind: string; id: string } | undefined {
+  const trimmed = subjectId.trim();
+  const index = trimmed.indexOf(":");
+  if (index <= 0 || index >= trimmed.length - 1) {
+    return undefined;
+  }
+  const kind = trimmed.slice(0, index).trim();
+  const id = trimmed.slice(index + 1).trim();
+  if (!kind || !id) {
+    return undefined;
+  }
+  return { kind, id };
+}
+
 export function request(
   token = "",
   connectionParams: Record<string, string> = {},
@@ -157,18 +167,12 @@ export function request(
     },
     subject: {
       id: subject.id ?? "",
-      kind: subject.kind ?? "",
       credentialSubjectId: subject.credentialSubjectId ?? "",
-      displayName: subject.displayName ?? "",
-      authSource: subject.authSource ?? "",
       email: subject.email ?? "",
     },
     agentSubject: {
       id: agentSubject.id ?? "",
-      kind: agentSubject.kind ?? "",
       credentialSubjectId: agentSubject.credentialSubjectId ?? "",
-      displayName: agentSubject.displayName ?? "",
-      authSource: agentSubject.authSource ?? "",
       email: agentSubject.email ?? "",
     },
     credential: {

package/src/app-access.ts

@@ -8,6 +8,7 @@ import {
   structFromObject,
   type JsonObjectInput,
 } from "./protocol.ts";
+import { hostInvocationContext } from "./invocation-context.ts";
 import {
   createHostServiceGrpcTransport,
   hostServiceMetadataInterceptors,
@@ -72,12 +73,12 @@ export interface App {
  */
 class AppImpl implements App {
   private readonly client: Client<typeof AppService>;
-  private readonly invocationToken: string;
+  private readonly invocationContext: ReturnType<typeof hostInvocationContext>;
 
   constructor(request: Request);
   constructor(invocationToken: string);
   constructor(requestOrToken: Request | string) {
-    this.invocationToken = normalizeInvocationToken(requestOrToken);
+    this.invocationContext = hostInvocationContext(requestOrToken);
 
     const { target, token } = requireHostServiceTarget("app");
     const transport = createHostServiceGrpcTransport(
@@ -95,7 +96,7 @@ class AppImpl implements App {
     options?: AppInvokeOptions,
   ): Promise<OperationResult> {
     const response = await this.client.invoke({
-      invocationToken: this.invocationToken,
+      ...this.invocationContext,
       app,
       operation,
       params: structFromObject(params),
@@ -123,7 +124,7 @@ class AppImpl implements App {
     }
 
     const response = await this.client.invokeGraphQL({
-      invocationToken: this.invocationToken,
+      invocationToken: this.invocationContext.invocationToken,
       app,
       document: trimmedDocument,
       ...(options?.variables !== undefined
@@ -148,7 +149,7 @@ class AppImpl implements App {
     ttlSeconds?: number;
   }): Promise<string> {
     const response = await this.client.exchangeInvocationToken({
-      parentInvocationToken: this.invocationToken,
+      parentInvocationToken: this.invocationContext.invocationToken,
       grants: (options?.grants ?? [])
         .map((grant) => ({
           app: grant.app.trim(),
@@ -168,15 +169,3 @@ class AppImpl implements App {
 }
 
 export const App = AppImpl;
-
-function normalizeInvocationToken(requestOrToken: Request | string): string {
-  const invocationToken =
-    typeof requestOrToken === "string"
-      ? requestOrToken
-      : requestOrToken.invocationToken;
-  const trimmed = invocationToken.trim();
-  if (!trimmed) {
-    throw new Error("app: invocation token is not available");
-  }
-  return trimmed;
-}