@valon-technologies/gestalt 0.0.1-alpha.36 → 0.0.1-alpha.37

package/package.json

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

package/src/agent-access.ts

@@ -37,7 +37,6 @@ import {
   dateFromTimestamp,
   type JsonObjectInput,
 } from "./protocol.ts";
-import { hostInvocationContext } from "./invocation-context.ts";
 import {
   optionalObjectFromStruct,
   optionalStruct,
@@ -49,6 +48,7 @@ import {
   ENV_HOST_SERVICE_SOCKET,
   ENV_HOST_SERVICE_TOKEN,
 } from "./host-service.ts";
+import { hostInvocationContext } from "./invocation-context.ts";
 
 export interface AgentWorkspaceGitCheckout {
   url?: string | undefined;
@@ -165,9 +165,6 @@ export interface Agent {
 
 /**
  * Client for managing agent sessions, turns, events, and interactions.
- *
- * The constructor accepts either a Gestalt request or an invocation token. Each
- * agent call forwards that token to the agent-provider facade.
  */
 class AgentImpl implements Agent {
   private readonly client: Client<typeof AgentProviderService>;
@@ -219,7 +216,7 @@ class AgentImpl implements Agent {
     );
   }
 
-  /** Lists agent sessions visible to the invocation token. */
+  /** Lists agent sessions visible to the request context. */
   async listSessions(
     request: AgentListSessions = {},
   ): Promise<AgentSession[]> {

package/src/agent-conversions.ts

@@ -21,8 +21,10 @@ import {
 } from "./internal/gen/v1/agent_pb.ts";
 import {
   SubjectContextSchema,
+  SubjectPermissionContextSchema,
   AgentToolRefSchema,
   type SubjectContext as ProtoSubjectContext,
+  type SubjectPermissionContext as ProtoSubjectPermissionContext,
   type AgentToolRef as ProtoAgentToolRef,
 } from "./internal/gen/v1/app_pb.ts";
 import {
@@ -43,7 +45,7 @@ import type {
   AgentTurnOutput,
   AgentTurnDisplay,
 } from "./agent.ts";
-import type { Subject, SubjectInput } from "./api.ts";
+import type { Subject, SubjectInput, SubjectPermission } from "./api.ts";
 
 export function agentTurnDisplayFromProto(
   display?: ProtoAgentTurnDisplay | undefined,
@@ -299,11 +301,14 @@ function agentRunAsSubjectFromProto(
     id: subject.id,
     credentialSubjectId: subject.credentialSubjectId,
     email: subject.email,
+    displayName: subject.displayName,
+    scopes: [...subject.scopes],
+    permissions: subjectPermissionsFromProto(subject.permissions),
   };
 }
 
 function agentRunAsSubjectToProto(
-  subject?: SubjectInput | undefined,
+  subject?: SubjectInput | Subject | undefined,
 ): ProtoSubjectContext | undefined {
   if (subject === undefined) {
     return undefined;
@@ -312,5 +317,27 @@ function agentRunAsSubjectToProto(
     id: subject.id ?? "",
     credentialSubjectId: subject.credentialSubjectId ?? "",
     email: subject.email ?? "",
+    displayName: subject.displayName ?? "",
+    scopes: [...(subject.scopes ?? [])],
+    permissions: subjectPermissionsToProto(subject.permissions),
   });
 }
+
+function subjectPermissionsFromProto(
+  permissions: readonly ProtoSubjectPermissionContext[],
+): SubjectPermission[] {
+  return permissions.map((permission) => ({
+    app: permission.app,
+    operations: permission.allOperations ? [] : [...permission.operations],
+  }));
+}
+
+function subjectPermissionsToProto(
+  permissions?: readonly SubjectPermission[] | undefined,
+): ProtoSubjectPermissionContext[] {
+  return permissions?.map((permission) => create(SubjectPermissionContextSchema, {
+    app: permission.app,
+    operations: [...permission.operations],
+    allOperations: permission.operations.length === 0,
+  })) ?? [];
+}

package/src/agent.ts

@@ -70,13 +70,16 @@ import {
 } from "./internal/gen/v1/agent_pb.ts";
 import {
   type SubjectContext as ProtoSubjectContext,
+  type SubjectPermissionContext as ProtoSubjectPermissionContext,
   type AgentToolRef as ProtoAgentToolRef,
+  type RequestContext as ProtoRequestContext,
 } from "./internal/gen/v1/app_pb.ts";
 import {
   errorMessage,
   type MaybePromise,
   type Subject,
   type SubjectInput,
+  type SubjectPermission,
 } from "./api.ts";
 import {
   agentOutputFromProto,
@@ -274,24 +277,28 @@ export interface CreateAgentProviderSessionRequest {
   metadata?: JsonObjectInput | undefined;
   createdBySubjectId?: string | undefined;
   subject?: Subject | undefined;
+  invocationToken: string;
+  context?: ProtoRequestContext | undefined;
   sessionStart?: AgentSessionStartConfig | undefined;
   preparedWorkspace?: AgentPreparedWorkspace | undefined;
-  invocationToken: string;
 }
 
 export interface GetAgentProviderSessionRequest {
   sessionId: string;
   subject?: Subject | undefined;
   invocationToken: string;
+  context?: ProtoRequestContext | undefined;
 }
 
 export interface ListAgentProviderSessionsRequest {
+  providerName?: string | undefined;
   subject?: Subject | undefined;
+  invocationToken: string;
+  context?: ProtoRequestContext | undefined;
   sessionIds: readonly string[];
   state: AgentSessionState;
   limit: number;
   summaryOnly: boolean;
-  invocationToken: string;
 }
 
 export interface ListAgentProviderSessionsResponse {
@@ -305,6 +312,7 @@ export interface UpdateAgentProviderSessionRequest {
   metadata?: JsonObjectInput | undefined;
   subject?: Subject | undefined;
   invocationToken: string;
+  context?: ProtoRequestContext | undefined;
 }
 
 export interface AgentTurn {
@@ -363,8 +371,9 @@ export interface CreateAgentProviderTurnRequest {
   subject?: Subject | undefined;
   modelOptions?: JsonObjectInput | undefined;
   runGrant: string;
-  timeoutSeconds: number;
   invocationToken: string;
+  context?: ProtoRequestContext | undefined;
+  timeoutSeconds: number;
 }
 
 export interface AgentTextOutput {
@@ -382,16 +391,18 @@ export interface GetAgentProviderTurnRequest {
   turnId: string;
   subject?: Subject | undefined;
   invocationToken: string;
+  context?: ProtoRequestContext | undefined;
 }
 
 export interface ListAgentProviderTurnsRequest {
   sessionId: string;
   subject?: Subject | undefined;
+  invocationToken: string;
+  context?: ProtoRequestContext | undefined;
   turnIds: readonly string[];
   status: AgentExecutionStatus;
   limit: number;
   summaryOnly: boolean;
-  invocationToken: string;
 }
 
 export interface ListAgentProviderTurnsResponse {
@@ -403,6 +414,7 @@ export interface CancelAgentProviderTurnRequest {
   reason: string;
   subject?: Subject | undefined;
   invocationToken: string;
+  context?: ProtoRequestContext | undefined;
 }
 
 export interface AgentTurnEvent {
@@ -423,6 +435,7 @@ export interface ListAgentProviderTurnEventsRequest {
   limit: number;
   subject?: Subject | undefined;
   invocationToken: string;
+  context?: ProtoRequestContext | undefined;
 }
 
 export interface ListAgentProviderTurnEventsResponse {
@@ -447,12 +460,14 @@ export interface GetAgentProviderInteractionRequest {
   interactionId: string;
   subject?: Subject | undefined;
   invocationToken: string;
+  context?: ProtoRequestContext | undefined;
 }
 
 export interface ListAgentProviderInteractionsRequest {
   turnId: string;
   subject?: Subject | undefined;
   invocationToken: string;
+  context?: ProtoRequestContext | undefined;
 }
 
 export interface ListAgentProviderInteractionsResponse {
@@ -460,10 +475,12 @@ export interface ListAgentProviderInteractionsResponse {
 }
 
 export interface ResolveAgentProviderInteractionRequest {
+  turnId?: string | undefined;
   interactionId: string;
   resolution?: JsonObjectInput | undefined;
   subject?: Subject | undefined;
   invocationToken: string;
+  context?: ProtoRequestContext | undefined;
 }
 
 export interface GetAgentProviderCapabilitiesRequest {}
@@ -476,6 +493,7 @@ export interface ExecuteAgentToolRequest {
   arguments?: JsonObjectInput | undefined;
   idempotencyKey?: string | undefined;
   runGrant?: string | undefined;
+  context?: ProtoRequestContext | undefined;
 }
 
 export interface ExecuteAgentToolResponse {
@@ -508,8 +526,9 @@ export interface ListAgentToolsRequest {
   turnId: string;
   pageSize?: number | undefined;
   pageToken?: string | undefined;
-  runGrant?: string | undefined;
   query?: string | undefined;
+  runGrant?: string | undefined;
+  context?: ProtoRequestContext | undefined;
 }
 
 export interface ListAgentToolsResponse {
@@ -523,6 +542,7 @@ export interface ResolveAgentConnectionRequest {
   connection: string;
   instance?: string | undefined;
   runGrant?: string | undefined;
+  context?: ProtoRequestContext | undefined;
 }
 
 export interface ResolvedAgentConnection {
@@ -538,10 +558,11 @@ export interface ResolvedAgentConnection {
 export interface AgentHostListToolsInput {
   sessionId: string;
   turnId: string;
-  runGrant?: string | undefined;
   pageSize?: number | undefined;
   pageToken?: string | undefined;
   query?: string | undefined;
+  runGrant?: string | undefined;
+  context?: ProtoRequestContext | undefined;
 }
 
 /** Plain-object input for executing a tool during one agent turn. */
@@ -551,8 +572,9 @@ export interface AgentHostExecuteToolInput {
   toolCallId: string;
   toolId: string;
   arguments?: JsonObjectInput | undefined;
-  runGrant?: string | undefined;
   idempotencyKey?: string | undefined;
+  runGrant?: string | undefined;
+  context?: ProtoRequestContext | undefined;
 }
 
 /** Plain-object input for resolving a configured connection during one turn. */
@@ -562,6 +584,7 @@ export interface AgentHostResolveConnectionInput {
   connection: string;
   instance?: string | undefined;
   runGrant?: string | undefined;
+  context?: ProtoRequestContext | undefined;
 }
 
 /** Fakeable client contract for agent host calls. */
@@ -808,7 +831,9 @@ function createAgentProviderSessionRequestFromProto(
     clientRef: request.clientRef,
     metadata: optionalObjectFromStruct(request.metadata),
     createdBySubjectId: request.createdBySubjectId ?? "",
-    subject: agentSubjectFromProto(request.subject),
+    subject: agentRequestSubjectFromProto(request),
+    invocationToken: request.invocationToken,
+    context: request.context,
     sessionStart: request.sessionStart === undefined ? undefined : {
       hooks: request.sessionStart.hooks.map((hook) => ({
         id: hook.id,
@@ -827,7 +852,6 @@ function createAgentProviderSessionRequestFromProto(
       root: request.preparedWorkspace.root,
       cwd: request.preparedWorkspace.cwd,
     },
-    invocationToken: request.invocationToken,
   };
 }
 
@@ -836,8 +860,9 @@ function getAgentProviderSessionRequestFromProto(
 ): GetAgentProviderSessionRequest {
   return {
     sessionId: request.sessionId,
-    subject: agentSubjectFromProto(request.subject),
+    subject: agentRequestSubjectFromProto(request),
     invocationToken: request.invocationToken,
+    context: request.context,
   };
 }
 
@@ -845,12 +870,14 @@ function listAgentProviderSessionsRequestFromProto(
   request: ProtoListAgentProviderSessionsRequest,
 ): ListAgentProviderSessionsRequest {
   return {
-    subject: agentSubjectFromProto(request.subject),
+    providerName: request.providerName,
+    subject: agentRequestSubjectFromProto(request),
+    invocationToken: request.invocationToken,
+    context: request.context,
     sessionIds: [...request.sessionIds],
     state: request.state as AgentSessionState,
     limit: request.limit,
     summaryOnly: request.summaryOnly,
-    invocationToken: request.invocationToken,
   };
 }
 
@@ -862,8 +889,9 @@ function updateAgentProviderSessionRequestFromProto(
     clientRef: request.clientRef,
     state: request.state as AgentSessionState,
     metadata: optionalObjectFromStruct(request.metadata),
-    subject: agentSubjectFromProto(request.subject),
+    subject: agentRequestSubjectFromProto(request),
     invocationToken: request.invocationToken,
+    context: request.context,
   };
 }
 
@@ -898,11 +926,12 @@ function createAgentProviderTurnRequestFromProto(
     executionRef: request.executionRef,
     toolRefs: request.toolRefs.map(agentToolRefFromProto),
     toolSource: request.toolSource as AgentToolSourceMode,
-    subject: agentSubjectFromProto(request.subject),
+    subject: agentRequestSubjectFromProto(request),
     modelOptions: optionalObjectFromStruct(request.modelOptions),
     runGrant: request.runGrant,
-    timeoutSeconds: request.timeoutSeconds,
     invocationToken: request.invocationToken,
+    context: request.context,
+    timeoutSeconds: request.timeoutSeconds,
   };
 }
 
@@ -911,8 +940,9 @@ function getAgentProviderTurnRequestFromProto(
 ): GetAgentProviderTurnRequest {
   return {
     turnId: request.turnId,
-    subject: agentSubjectFromProto(request.subject),
+    subject: agentRequestSubjectFromProto(request),
     invocationToken: request.invocationToken,
+    context: request.context,
   };
 }
 
@@ -921,12 +951,13 @@ function listAgentProviderTurnsRequestFromProto(
 ): ListAgentProviderTurnsRequest {
   return {
     sessionId: request.sessionId,
-    subject: agentSubjectFromProto(request.subject),
+    subject: agentRequestSubjectFromProto(request),
+    invocationToken: request.invocationToken,
+    context: request.context,
     turnIds: [...request.turnIds],
     status: request.status as AgentExecutionStatus,
     limit: request.limit,
     summaryOnly: request.summaryOnly,
-    invocationToken: request.invocationToken,
   };
 }
 
@@ -936,8 +967,9 @@ function cancelAgentProviderTurnRequestFromProto(
   return {
     turnId: request.turnId,
     reason: request.reason,
-    subject: agentSubjectFromProto(request.subject),
+    subject: agentRequestSubjectFromProto(request),
     invocationToken: request.invocationToken,
+    context: request.context,
   };
 }
 
@@ -948,8 +980,9 @@ function listAgentProviderTurnEventsRequestFromProto(
     turnId: request.turnId,
     afterSeq: request.afterSeq,
     limit: request.limit,
-    subject: agentSubjectFromProto(request.subject),
+    subject: agentRequestSubjectFromProto(request),
     invocationToken: request.invocationToken,
+    context: request.context,
   };
 }
 
@@ -958,8 +991,9 @@ function getAgentProviderInteractionRequestFromProto(
 ): GetAgentProviderInteractionRequest {
   return {
     interactionId: request.interactionId,
-    subject: agentSubjectFromProto(request.subject),
+    subject: agentRequestSubjectFromProto(request),
     invocationToken: request.invocationToken,
+    context: request.context,
   };
 }
 
@@ -968,8 +1002,9 @@ function listAgentProviderInteractionsRequestFromProto(
 ): ListAgentProviderInteractionsRequest {
   return {
     turnId: request.turnId,
-    subject: agentSubjectFromProto(request.subject),
+    subject: agentRequestSubjectFromProto(request),
     invocationToken: request.invocationToken,
+    context: request.context,
   };
 }
 
@@ -977,10 +1012,12 @@ function resolveAgentProviderInteractionRequestFromProto(
   request: ProtoResolveAgentProviderInteractionRequest,
 ): ResolveAgentProviderInteractionRequest {
   return {
+    turnId: request.turnId,
     interactionId: request.interactionId,
     resolution: optionalObjectFromStruct(request.resolution),
-    subject: agentSubjectFromProto(request.subject),
+    subject: agentRequestSubjectFromProto(request),
     invocationToken: request.invocationToken,
+    context: request.context,
   };
 }
 
@@ -1079,6 +1116,15 @@ function resolvedAgentToolFromProto(tool: ProtoResolvedAgentTool): ResolvedAgent
   };
 }
 
+function agentRequestSubjectFromProto(
+  request: {
+    context?: { subject?: ProtoSubjectContext | undefined } | undefined;
+    subject?: ProtoSubjectContext | undefined;
+  },
+): Subject | undefined {
+  return agentSubjectFromProto(request.context?.subject ?? request.subject);
+}
+
 function agentSubjectFromProto(
   subject?: ProtoSubjectContext | undefined,
 ): Subject | undefined {
@@ -1089,9 +1135,21 @@ function agentSubjectFromProto(
     id: subject.id,
     credentialSubjectId: subject.credentialSubjectId,
     email: subject.email,
+    displayName: subject.displayName,
+    scopes: [...subject.scopes],
+    permissions: agentSubjectPermissionsFromProto(subject.permissions),
   };
 }
 
+function agentSubjectPermissionsFromProto(
+  permissions: readonly ProtoSubjectPermissionContext[],
+): SubjectPermission[] {
+  return permissions.map((permission) => ({
+    app: permission.app,
+    operations: permission.allOperations ? [] : [...permission.operations],
+  }));
+}
+
 function optionalTimestamp(value?: Date | undefined) {
   return value === undefined ? undefined : timestampFromDate(value);
 }
@@ -1107,6 +1165,7 @@ function executeToolRequestToProto(
     arguments: optionalStruct(request.arguments),
     idempotencyKey: request.idempotencyKey ?? "",
     runGrant: request.runGrant ?? "",
+    context: request.context,
   });
 }
 
@@ -1125,8 +1184,9 @@ function listToolsRequestToProto(request: ListAgentToolsRequest): ProtoListAgent
     turnId: request.turnId,
     pageSize: request.pageSize ?? 0,
     pageToken: request.pageToken ?? "",
-    runGrant: request.runGrant ?? "",
     query: request.query ?? "",
+    runGrant: request.runGrant ?? "",
+    context: request.context,
   });
 }
 
@@ -1168,6 +1228,7 @@ function resolveConnectionRequestToProto(
     connection: request.connection,
     instance: request.instance ?? "",
     runGrant: request.runGrant ?? "",
+    context: request.context,
   });
 }
 
@@ -1237,8 +1298,9 @@ class AgentHostImpl implements AgentHost {
         toolCallId: input.toolCallId,
         toolId: input.toolId,
         arguments: input.arguments,
-        runGrant: input.runGrant ?? "",
         idempotencyKey: input.idempotencyKey ?? "",
+        runGrant: input.runGrant ?? "",
+        context: input.context,
       },
     );
   }
@@ -1260,10 +1322,11 @@ class AgentHostImpl implements AgentHost {
       {
         sessionId: input.sessionId,
         turnId: input.turnId,
-        runGrant: input.runGrant ?? "",
         pageSize: input.pageSize ?? 0,
         pageToken: input.pageToken ?? "",
         query: input.query ?? "",
+        runGrant: input.runGrant ?? "",
+        context: input.context,
       },
     );
   }
@@ -1288,6 +1351,7 @@ class AgentHostImpl implements AgentHost {
         connection: input.connection,
         instance: input.instance ?? "",
         runGrant: input.runGrant ?? "",
+        context: input.context,
       },
     );
   }

package/src/api.ts

@@ -2,16 +2,24 @@
  * Common request and response types shared across authored Gestalt providers.
  */
 import type { AgentToolRef } from "./agent.ts";
+import type { RequestContext as ProtoRequestContext } from "./internal/gen/v1/app_pb.ts";
 
 export interface Subject {
   id: string;
   credentialSubjectId: string;
   email: string;
+  scopes?: string[] | undefined;
+  permissions?: SubjectPermission[] | undefined;
   kind?: string | undefined;
   displayName?: string | undefined;
   authSource?: string | undefined;
 }
 
+export interface SubjectPermission {
+  app: string;
+  operations: string[];
+}
+
 /**
  * Subject payload authored by provider-side hooks.
  */
@@ -19,6 +27,9 @@ export interface SubjectInput {
   id: string;
   credentialSubjectId?: string | undefined;
   email?: string | undefined;
+  displayName?: string | undefined;
+  scopes?: readonly string[] | undefined;
+  permissions?: readonly SubjectPermission[] | undefined;
 }
 
 /**
@@ -64,6 +75,7 @@ export interface Request {
   toolRefs: AgentToolRef[];
   toolRefsSet: boolean;
   invocationToken: string;
+  __requestContext?: ProtoRequestContext | undefined;
 }
 
 /**
@@ -162,6 +174,7 @@ export function request(
   agentSubject: Partial<Subject> = {},
   toolRefs: readonly AgentToolRef[] = [],
   toolRefsSet = false,
+  requestContext?: ProtoRequestContext,
 ): Request {
   return {
     token,
@@ -172,6 +185,8 @@ export function request(
       id: subject.id ?? "",
       credentialSubjectId: subject.credentialSubjectId ?? "",
       email: subject.email ?? "",
+      scopes: [...(subject.scopes ?? [])],
+      permissions: cloneSubjectPermissions(subject.permissions),
       kind: subject.kind,
       displayName: subject.displayName,
       authSource: subject.authSource,
@@ -180,6 +195,8 @@ export function request(
       id: agentSubject.id ?? "",
       credentialSubjectId: agentSubject.credentialSubjectId ?? "",
       email: agentSubject.email ?? "",
+      scopes: [...(agentSubject.scopes ?? [])],
+      permissions: cloneSubjectPermissions(agentSubject.permissions),
       kind: agentSubject.kind,
       displayName: agentSubject.displayName,
       authSource: agentSubject.authSource,
@@ -199,17 +216,35 @@ export function request(
     },
     toolRefs: toolRefs.map((ref) => ({
       ...ref,
-      runAs: ref.runAs === undefined ? undefined : { ...ref.runAs },
+      runAs: ref.runAs === undefined ? undefined : cloneSubjectInput(ref.runAs),
     })),
     toolRefsSet,
     host: {
       publicBaseUrl: host.publicBaseUrl ?? "",
     },
     invocationToken,
+    __requestContext: requestContext,
     idempotencyKey: idempotencyKey.trim(),
   };
 }
 
+export function cloneSubjectInput<T extends SubjectInput | Subject>(subject: T): T {
+  return {
+    ...subject,
+    scopes: [...(subject.scopes ?? [])],
+    permissions: cloneSubjectPermissions(subject.permissions),
+  };
+}
+
+export function cloneSubjectPermissions(
+  permissions?: readonly SubjectPermission[] | undefined,
+): SubjectPermission[] {
+  return permissions?.map((permission) => ({
+    app: permission.app,
+    operations: [...permission.operations],
+  })) ?? [];
+}
+
 /**
  * Looks up a single connection parameter from a request.
  */

package/src/app-access.ts

@@ -27,6 +27,7 @@ export interface AppInvokeOptions {
   /** Credential mode requested for the target operation. */
   credentialMode?: ConnectionMode;
 }
+
 /** Grant included when exchanging an invocation token for a child token. */
 export interface AppInvocationGrant {
   /** App name that the child token may invoke. */
@@ -68,8 +69,9 @@ export interface App {
 /**
  * Transport-backed implementation for invoking sibling app operations.
  *
- * The constructor accepts either a Gestalt request or an invocation token. The
- * token is attached to every operation, GraphQL, and token-exchange request.
+ * The constructor accepts either a Gestalt request or an invocation token. A
+ * request forwards both its host request context and legacy invocation token
+ * when available.
  */
 class AppImpl implements App {
   private readonly client: Client<typeof AppService>;
@@ -125,6 +127,7 @@ class AppImpl implements App {
 
     const response = await this.client.invokeGraphQL({
       invocationToken: this.invocationContext.invocationToken,
+      context: this.invocationContext.context,
       app,
       document: trimmedDocument,
       ...(options?.variables !== undefined

package/src/index.ts

@@ -78,8 +78,8 @@ export {
 } from "./build.ts";
 export {
   App,
-  type AppGraphQLInvokeOptions,
   type AppInvocationGrant,
+  type AppGraphQLInvokeOptions,
   type AppInvokeOptions,
 } from "./app-access.ts";
 export {