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

package/src/agent.ts

@@ -0,0 +1,492 @@
+import { connect } from "node:net";
+
+import { create, type MessageInitShape } from "@bufbuild/protobuf";
+import {
+  Code,
+  ConnectError,
+  createClient,
+  type Client,
+  type ServiceImpl,
+} from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+
+import {
+  AgentExecutionStatus,
+  AgentHost as AgentHostService,
+  AgentInteractionSchema,
+  AgentInteractionState,
+  AgentInteractionType,
+  AgentMessagePartType,
+  AgentProvider as AgentProviderService,
+  AgentProviderCapabilitiesSchema,
+  AgentSessionSchema,
+  AgentSessionState,
+  AgentToolSourceMode,
+  AgentTurnEventSchema,
+  AgentTurnSchema,
+  GetAgentProviderCapabilitiesRequestSchema,
+  ListAgentProviderInteractionsResponseSchema,
+  ListAgentProviderSessionsResponseSchema,
+  ListAgentProviderTurnEventsResponseSchema,
+  ListAgentProviderTurnsResponseSchema,
+  type AgentActor,
+  type AgentInteraction,
+  type AgentMessage,
+  type AgentMessagePart,
+  type AgentMessagePartImageRef,
+  type AgentMessagePartToolCall,
+  type AgentMessagePartToolResult,
+  type AgentProviderCapabilities,
+  type AgentSession,
+  type AgentToolRef,
+  type AgentTurn,
+  type AgentTurnEvent,
+  type BoundAgentToolTarget,
+  type CancelAgentProviderTurnRequest,
+  type CreateAgentProviderSessionRequest,
+  type CreateAgentProviderTurnRequest,
+  type ExecuteAgentToolRequest,
+  type ExecuteAgentToolResponse,
+  type GetAgentProviderCapabilitiesRequest,
+  type GetAgentProviderInteractionRequest,
+  type GetAgentProviderSessionRequest,
+  type GetAgentProviderTurnRequest,
+  type ListAgentProviderInteractionsRequest,
+  type ListAgentProviderSessionsRequest,
+  type ListAgentProviderTurnEventsRequest,
+  type ListAgentProviderTurnsRequest,
+  type ResolveAgentProviderInteractionRequest,
+  type ResolvedAgentTool,
+  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 type {
+  AgentActor,
+  AgentInteraction,
+  AgentMessage,
+  AgentMessagePart,
+  AgentMessagePartImageRef,
+  AgentMessagePartToolCall,
+  AgentMessagePartToolResult,
+  AgentProviderCapabilities,
+  AgentSession,
+  AgentToolRef,
+  AgentTurn,
+  AgentTurnEvent,
+  BoundAgentToolTarget,
+  CancelAgentProviderTurnRequest,
+  CreateAgentProviderSessionRequest,
+  CreateAgentProviderTurnRequest,
+  ExecuteAgentToolRequest,
+  ExecuteAgentToolResponse,
+  GetAgentProviderCapabilitiesRequest,
+  GetAgentProviderInteractionRequest,
+  GetAgentProviderSessionRequest,
+  GetAgentProviderTurnRequest,
+  ListAgentProviderInteractionsRequest,
+  ListAgentProviderSessionsRequest,
+  ListAgentProviderTurnEventsRequest,
+  ListAgentProviderTurnsRequest,
+  ResolveAgentProviderInteractionRequest,
+  ResolvedAgentTool,
+  UpdateAgentProviderSessionRequest,
+};
+export {
+  AgentExecutionStatus,
+  AgentInteractionState,
+  AgentInteractionType,
+  AgentMessagePartType,
+  AgentSessionState,
+  AgentToolSourceMode,
+};
+
+export interface AgentProviderOptions extends RuntimeProviderOptions {
+  createSession?: (
+    request: CreateAgentProviderSessionRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentSessionSchema>>;
+  getSession?: (
+    request: GetAgentProviderSessionRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentSessionSchema>>;
+  listSessions?: (
+    request: ListAgentProviderSessionsRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentSessionSchema>[]>;
+  updateSession?: (
+    request: UpdateAgentProviderSessionRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentSessionSchema>>;
+  createTurn?: (
+    request: CreateAgentProviderTurnRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentTurnSchema>>;
+  getTurn?: (
+    request: GetAgentProviderTurnRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentTurnSchema>>;
+  listTurns?: (
+    request: ListAgentProviderTurnsRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentTurnSchema>[]>;
+  cancelTurn?: (
+    request: CancelAgentProviderTurnRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentTurnSchema>>;
+  listTurnEvents?: (
+    request: ListAgentProviderTurnEventsRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentTurnEventSchema>[]>;
+  getInteraction?: (
+    request: GetAgentProviderInteractionRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentInteractionSchema>>;
+  listInteractions?: (
+    request: ListAgentProviderInteractionsRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentInteractionSchema>[]>;
+  resolveInteraction?: (
+    request: ResolveAgentProviderInteractionRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentInteractionSchema>>;
+  getCapabilities?: (
+    request: GetAgentProviderCapabilitiesRequest,
+  ) => MaybePromise<MessageInitShape<typeof AgentProviderCapabilitiesSchema>>;
+}
+
+export class AgentProvider extends RuntimeProvider {
+  readonly kind = "agent" as const;
+
+  private readonly createSessionHandler: AgentProviderOptions["createSession"];
+  private readonly getSessionHandler: AgentProviderOptions["getSession"];
+  private readonly listSessionsHandler: AgentProviderOptions["listSessions"];
+  private readonly updateSessionHandler: AgentProviderOptions["updateSession"];
+  private readonly createTurnHandler: AgentProviderOptions["createTurn"];
+  private readonly getTurnHandler: AgentProviderOptions["getTurn"];
+  private readonly listTurnsHandler: AgentProviderOptions["listTurns"];
+  private readonly cancelTurnHandler: AgentProviderOptions["cancelTurn"];
+  private readonly listTurnEventsHandler: AgentProviderOptions["listTurnEvents"];
+  private readonly getInteractionHandler: AgentProviderOptions["getInteraction"];
+  private readonly listInteractionsHandler: AgentProviderOptions["listInteractions"];
+  private readonly resolveInteractionHandler: AgentProviderOptions["resolveInteraction"];
+  private readonly getCapabilitiesHandler: AgentProviderOptions["getCapabilities"];
+
+  constructor(options: AgentProviderOptions) {
+    super(options);
+    this.createSessionHandler = options.createSession;
+    this.getSessionHandler = options.getSession;
+    this.listSessionsHandler = options.listSessions;
+    this.updateSessionHandler = options.updateSession;
+    this.createTurnHandler = options.createTurn;
+    this.getTurnHandler = options.getTurn;
+    this.listTurnsHandler = options.listTurns;
+    this.cancelTurnHandler = options.cancelTurn;
+    this.listTurnEventsHandler = options.listTurnEvents;
+    this.getInteractionHandler = options.getInteraction;
+    this.listInteractionsHandler = options.listInteractions;
+    this.resolveInteractionHandler = options.resolveInteraction;
+    this.getCapabilitiesHandler = options.getCapabilities;
+  }
+
+  async createSession(
+    request: CreateAgentProviderSessionRequest,
+  ): Promise<MessageInitShape<typeof AgentSessionSchema>> {
+    return await requireAgentProviderHandler(
+      "create session",
+      this.createSessionHandler,
+      request,
+    );
+  }
+
+  async getSession(
+    request: GetAgentProviderSessionRequest,
+  ): Promise<MessageInitShape<typeof AgentSessionSchema>> {
+    return await requireAgentProviderHandler(
+      "get session",
+      this.getSessionHandler,
+      request,
+    );
+  }
+
+  async listSessions(
+    request: ListAgentProviderSessionsRequest,
+  ): Promise<MessageInitShape<typeof AgentSessionSchema>[]> {
+    return await requireAgentProviderHandler(
+      "list sessions",
+      this.listSessionsHandler,
+      request,
+    );
+  }
+
+  async updateSession(
+    request: UpdateAgentProviderSessionRequest,
+  ): Promise<MessageInitShape<typeof AgentSessionSchema>> {
+    return await requireAgentProviderHandler(
+      "update session",
+      this.updateSessionHandler,
+      request,
+    );
+  }
+
+  async createTurn(
+    request: CreateAgentProviderTurnRequest,
+  ): Promise<MessageInitShape<typeof AgentTurnSchema>> {
+    return await requireAgentProviderHandler(
+      "create turn",
+      this.createTurnHandler,
+      request,
+    );
+  }
+
+  async getTurn(
+    request: GetAgentProviderTurnRequest,
+  ): Promise<MessageInitShape<typeof AgentTurnSchema>> {
+    return await requireAgentProviderHandler(
+      "get turn",
+      this.getTurnHandler,
+      request,
+    );
+  }
+
+  async listTurns(
+    request: ListAgentProviderTurnsRequest,
+  ): Promise<MessageInitShape<typeof AgentTurnSchema>[]> {
+    return await requireAgentProviderHandler(
+      "list turns",
+      this.listTurnsHandler,
+      request,
+    );
+  }
+
+  async cancelTurn(
+    request: CancelAgentProviderTurnRequest,
+  ): Promise<MessageInitShape<typeof AgentTurnSchema>> {
+    return await requireAgentProviderHandler(
+      "cancel turn",
+      this.cancelTurnHandler,
+      request,
+    );
+  }
+
+  async listTurnEvents(
+    request: ListAgentProviderTurnEventsRequest,
+  ): Promise<MessageInitShape<typeof AgentTurnEventSchema>[]> {
+    return await requireAgentProviderHandler(
+      "list turn events",
+      this.listTurnEventsHandler,
+      request,
+    );
+  }
+
+  async getInteraction(
+    request: GetAgentProviderInteractionRequest,
+  ): Promise<MessageInitShape<typeof AgentInteractionSchema>> {
+    return await requireAgentProviderHandler(
+      "get interaction",
+      this.getInteractionHandler,
+      request,
+    );
+  }
+
+  async listInteractions(
+    request: ListAgentProviderInteractionsRequest,
+  ): Promise<MessageInitShape<typeof AgentInteractionSchema>[]> {
+    return await requireAgentProviderHandler(
+      "list interactions",
+      this.listInteractionsHandler,
+      request,
+    );
+  }
+
+  async resolveInteraction(
+    request: ResolveAgentProviderInteractionRequest,
+  ): Promise<MessageInitShape<typeof AgentInteractionSchema>> {
+    return await requireAgentProviderHandler(
+      "resolve interaction",
+      this.resolveInteractionHandler,
+      request,
+    );
+  }
+
+  async getCapabilities(
+    request: GetAgentProviderCapabilitiesRequest = create(
+      GetAgentProviderCapabilitiesRequestSchema,
+      {},
+    ),
+  ): Promise<MessageInitShape<typeof AgentProviderCapabilitiesSchema>> {
+    return await requireAgentProviderHandler(
+      "get capabilities",
+      this.getCapabilitiesHandler,
+      request,
+    );
+  }
+}
+
+export function defineAgentProvider(options: AgentProviderOptions): AgentProvider {
+  return new AgentProvider(options);
+}
+
+export function isAgentProvider(value: unknown): value is AgentProvider {
+  return (
+    value instanceof AgentProvider ||
+    (typeof value === "object" &&
+      value !== null &&
+      "kind" in value &&
+      (value as { kind?: unknown }).kind === "agent" &&
+      "createSession" in value &&
+      "createTurn" in value)
+  );
+}
+
+export class AgentHost {
+  private readonly client: Client<typeof AgentHostService>;
+
+  constructor() {
+    const socketPath = process.env[ENV_AGENT_HOST_SOCKET];
+    if (!socketPath) {
+      throw new Error(`agent host: ${ENV_AGENT_HOST_SOCKET} is not set`);
+    }
+    const transport = createGrpcTransport({
+      baseUrl: "http://localhost",
+      nodeOptions: {
+        createConnection: () => connect(socketPath),
+      },
+    });
+    this.client = createClient(AgentHostService, transport);
+  }
+
+  async executeTool(
+    request: ExecuteAgentToolRequest,
+  ): Promise<ExecuteAgentToolResponse> {
+    return await this.client.executeTool(request);
+  }
+
+}
+
+export function createAgentProviderService(
+  provider: AgentProvider,
+): Partial<ServiceImpl<typeof AgentProviderService>> {
+  return {
+    async createSession(request) {
+      return create(
+        AgentSessionSchema,
+        await invokeAgentProvider("create session", () =>
+          provider.createSession(request),
+        ),
+      );
+    },
+    async getSession(request) {
+      return create(
+        AgentSessionSchema,
+        await invokeAgentProvider("get session", () =>
+          provider.getSession(request),
+        ),
+      );
+    },
+    async listSessions(request) {
+      return create(ListAgentProviderSessionsResponseSchema, {
+        sessions: await invokeAgentProvider("list sessions", () =>
+          provider.listSessions(request),
+        ),
+      });
+    },
+    async updateSession(request) {
+      return create(
+        AgentSessionSchema,
+        await invokeAgentProvider("update session", () =>
+          provider.updateSession(request),
+        ),
+      );
+    },
+    async createTurn(request) {
+      return create(
+        AgentTurnSchema,
+        await invokeAgentProvider("create turn", () =>
+          provider.createTurn(request),
+        ),
+      );
+    },
+    async getTurn(request) {
+      return create(
+        AgentTurnSchema,
+        await invokeAgentProvider("get turn", () => provider.getTurn(request)),
+      );
+    },
+    async listTurns(request) {
+      return create(ListAgentProviderTurnsResponseSchema, {
+        turns: await invokeAgentProvider("list turns", () =>
+          provider.listTurns(request),
+        ),
+      });
+    },
+    async cancelTurn(request) {
+      return create(
+        AgentTurnSchema,
+        await invokeAgentProvider("cancel turn", () =>
+          provider.cancelTurn(request),
+        ),
+      );
+    },
+    async listTurnEvents(request) {
+      return create(ListAgentProviderTurnEventsResponseSchema, {
+        events: await invokeAgentProvider("list turn events", () =>
+          provider.listTurnEvents(request),
+        ),
+      });
+    },
+    async getInteraction(request) {
+      return create(
+        AgentInteractionSchema,
+        await invokeAgentProvider("get interaction", () =>
+          provider.getInteraction(request),
+        ),
+      );
+    },
+    async listInteractions(request) {
+      return create(ListAgentProviderInteractionsResponseSchema, {
+        interactions: await invokeAgentProvider("list interactions", () =>
+          provider.listInteractions(request),
+        ),
+      });
+    },
+    async resolveInteraction(request) {
+      return create(
+        AgentInteractionSchema,
+        await invokeAgentProvider("resolve interaction", () =>
+          provider.resolveInteraction(request),
+        ),
+      );
+    },
+    async getCapabilities(request) {
+      return create(
+        AgentProviderCapabilitiesSchema,
+        await invokeAgentProvider("get capabilities", () =>
+          provider.getCapabilities(request),
+        ),
+      );
+    },
+  };
+}
+
+async function requireAgentProviderHandler<Request, Response>(
+  action: string,
+  fn: ((request: Request) => MaybePromise<Response>) | undefined,
+  request: Request,
+): Promise<Response> {
+  if (!fn) {
+    throw new ConnectError(
+      `agent provider ${action} is not implemented`,
+      Code.Unimplemented,
+    );
+  }
+  return await fn(request);
+}
+
+async function invokeAgentProvider<T>(
+  action: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof ConnectError) {
+      throw error;
+    }
+    throw new ConnectError(
+      `agent provider ${action}: ${errorMessage(error)}`,
+      Code.Unknown,
+    );
+  }
+}

package/src/authorization.ts

@@ -1,7 +1,11 @@
 import { connect } from "node:net";
 
 import type { MessageInitShape } from "@bufbuild/protobuf";
-import { createClient, type Client } from "@connectrpc/connect";
+import {
+  createClient,
+  type Client,
+  type Interceptor,
+} from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
 
 import {
@@ -20,10 +24,14 @@ import {
 } from "../gen/v1/authorization_pb.ts";
 
 /**
- * Environment variable containing the Unix socket path for the read-only host
- * authorization client exposed to plugins.
+ * Environment variable containing the Unix socket path or relay target for the
+ * read-only host authorization client exposed to plugins.
  */
 export const ENV_AUTHORIZATION_SOCKET = "GESTALT_AUTHORIZATION_SOCKET";
+export const ENV_AUTHORIZATION_SOCKET_TOKEN =
+  `${ENV_AUTHORIZATION_SOCKET}_TOKEN`;
+const AUTHORIZATION_RELAY_TOKEN_HEADER =
+  "x-gestalt-host-service-relay-token";
 
 export type AuthorizationEvaluateInput = MessageInitShape<
   typeof AccessEvaluationRequestSchema
@@ -49,10 +57,12 @@ export type AuthorizationActionSearchMessage = ActionSearchResponse;
 export type AuthorizationReadRelationshipsMessage = ReadRelationshipsResponse;
 
 const sharedAuthorizationTransport: {
-  socketPath: string;
+  target: string;
+  token: string;
   client: AuthorizationClient | undefined;
 } = {
-  socketPath: "",
+  target: "",
+  token: "",
   client: undefined,
 };
 
@@ -62,13 +72,21 @@ const sharedAuthorizationTransport: {
 export class AuthorizationClient {
   private readonly client: Client<typeof AuthorizationProviderService>;
 
-  constructor(socketPath?: string) {
-    const resolvedSocketPath = resolveAuthorizationSocketPath(socketPath);
+  constructor(socketTarget?: string, relayToken = process.env[ENV_AUTHORIZATION_SOCKET_TOKEN]?.trim() ?? "") {
+    const resolvedTarget = resolveAuthorizationSocketTarget(socketTarget);
+    const transportOptions = authorizationTransportOptions(resolvedTarget);
     const transport = createGrpcTransport({
-      baseUrl: "http://localhost",
-      nodeOptions: {
-        createConnection: () => connect(resolvedSocketPath),
-      },
+      ...transportOptions,
+      ...(transportOptions.nodeOptions
+        ? {
+            nodeOptions: {
+              createConnection: () => connect(transportOptions.nodeOptions!.path),
+            },
+          }
+        : {}),
+      interceptors: relayToken
+        ? [authorizationRelayTokenInterceptor(relayToken)]
+        : [],
     });
     this.client = createClient(AuthorizationProviderService, transport);
   }
@@ -113,26 +131,78 @@ export class AuthorizationClient {
  * client inside authored providers.
  */
 export function Authorization(): AuthorizationClient {
-  const socketPath = resolveAuthorizationSocketPath();
+  const target = resolveAuthorizationSocketTarget();
+  const token = process.env[ENV_AUTHORIZATION_SOCKET_TOKEN]?.trim() ?? "";
   if (
     sharedAuthorizationTransport.client &&
-    sharedAuthorizationTransport.socketPath === socketPath
+    sharedAuthorizationTransport.target === target &&
+    sharedAuthorizationTransport.token === token
   ) {
     return sharedAuthorizationTransport.client;
   }
 
-  const client = new AuthorizationClient(socketPath);
-  sharedAuthorizationTransport.socketPath = socketPath;
+  const client = new AuthorizationClient(target, token);
+  sharedAuthorizationTransport.target = target;
+  sharedAuthorizationTransport.token = token;
   sharedAuthorizationTransport.client = client;
   return client;
 }
 
-function resolveAuthorizationSocketPath(socketPath = process.env[ENV_AUTHORIZATION_SOCKET]): string {
+function resolveAuthorizationSocketTarget(socketPath = process.env[ENV_AUTHORIZATION_SOCKET]): string {
   const trimmed = socketPath?.trim() ?? "";
   if (!trimmed) {
+    throw new Error(`authorization: ${ENV_AUTHORIZATION_SOCKET} is not set`);
+  }
+  return trimmed;
+}
+
+function authorizationTransportOptions(rawTarget: string): {
+  baseUrl: string;
+  nodeOptions?: { path: string };
+} {
+  const target = rawTarget.trim();
+  if (!target) {
+    throw new Error("authorization: transport target is required");
+  }
+  if (target.startsWith("tcp://")) {
+    const address = target.slice("tcp://".length).trim();
+    if (!address) {
+      throw new Error(
+        `authorization: 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(
+        `authorization: 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(
+        `authorization: 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(
-      `authorization: ${ENV_AUTHORIZATION_SOCKET} is not set`,
+      `authorization: unsupported target scheme ${JSON.stringify(parsed.protocol.replace(/:$/, ""))}`,
     );
   }
-  return trimmed;
+  return { baseUrl: "http://localhost", nodeOptions: { path: target } };
+}
+
+function authorizationRelayTokenInterceptor(token: string): Interceptor {
+  return (next) => async (req) => {
+    req.header.set(AUTHORIZATION_RELAY_TOKEN_HEADER, token);
+    return next(req);
+  };
 }