@valon-technologies/gestalt 0.0.1-alpha.11 → 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

@@ -0,0 +1,208 @@
+import { connect } from "node:net";
+
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import {
+  createClient,
+  type Client,
+  type Interceptor,
+} from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+
+import {
+  type AccessDecision,
+  type ActionSearchResponse,
+  type AuthorizationMetadata,
+  AuthorizationProvider as AuthorizationProviderService,
+  type ReadRelationshipsResponse,
+  type ResourceSearchResponse,
+  type SubjectSearchResponse,
+  AccessEvaluationRequestSchema,
+  ActionSearchRequestSchema,
+  ReadRelationshipsRequestSchema,
+  ResourceSearchRequestSchema,
+  SubjectSearchRequestSchema,
+} from "../gen/v1/authorization_pb.ts";
+
+/**
+ * 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
+>;
+export type AuthorizationSearchResourcesInput = MessageInitShape<
+  typeof ResourceSearchRequestSchema
+>;
+export type AuthorizationSearchSubjectsInput = MessageInitShape<
+  typeof SubjectSearchRequestSchema
+>;
+export type AuthorizationSearchActionsInput = MessageInitShape<
+  typeof ActionSearchRequestSchema
+>;
+export type AuthorizationReadRelationshipsInput = MessageInitShape<
+  typeof ReadRelationshipsRequestSchema
+>;
+
+export type AuthorizationDecisionMessage = AccessDecision;
+export type AuthorizationMetadataMessage = AuthorizationMetadata;
+export type AuthorizationResourceSearchMessage = ResourceSearchResponse;
+export type AuthorizationSubjectSearchMessage = SubjectSearchResponse;
+export type AuthorizationActionSearchMessage = ActionSearchResponse;
+export type AuthorizationReadRelationshipsMessage = ReadRelationshipsResponse;
+
+const sharedAuthorizationTransport: {
+  target: string;
+  token: string;
+  client: AuthorizationClient | undefined;
+} = {
+  target: "",
+  token: "",
+  client: undefined,
+};
+
+/**
+ * Read-only client for the host-configured authorization provider.
+ */
+export class AuthorizationClient {
+  private readonly client: Client<typeof AuthorizationProviderService>;
+
+  constructor(socketTarget?: string, relayToken = process.env[ENV_AUTHORIZATION_SOCKET_TOKEN]?.trim() ?? "") {
+    const resolvedTarget = resolveAuthorizationSocketTarget(socketTarget);
+    const transportOptions = authorizationTransportOptions(resolvedTarget);
+    const transport = createGrpcTransport({
+      ...transportOptions,
+      ...(transportOptions.nodeOptions
+        ? {
+            nodeOptions: {
+              createConnection: () => connect(transportOptions.nodeOptions!.path),
+            },
+          }
+        : {}),
+      interceptors: relayToken
+        ? [authorizationRelayTokenInterceptor(relayToken)]
+        : [],
+    });
+    this.client = createClient(AuthorizationProviderService, transport);
+  }
+
+  async evaluate(
+    request: AuthorizationEvaluateInput,
+  ): Promise<AuthorizationDecisionMessage> {
+    return await this.client.evaluate(request);
+  }
+
+  async searchResources(
+    request: AuthorizationSearchResourcesInput,
+  ): Promise<AuthorizationResourceSearchMessage> {
+    return await this.client.searchResources(request);
+  }
+
+  async searchSubjects(
+    request: AuthorizationSearchSubjectsInput,
+  ): Promise<AuthorizationSubjectSearchMessage> {
+    return await this.client.searchSubjects(request);
+  }
+
+  async searchActions(
+    request: AuthorizationSearchActionsInput,
+  ): Promise<AuthorizationActionSearchMessage> {
+    return await this.client.searchActions(request);
+  }
+
+  async readRelationships(
+    request: AuthorizationReadRelationshipsInput,
+  ): Promise<AuthorizationReadRelationshipsMessage> {
+    return await this.client.readRelationships(request);
+  }
+
+  async getMetadata(): Promise<AuthorizationMetadataMessage> {
+    return await this.client.getMetadata({});
+  }
+}
+
+/**
+ * Mirrors the Go SDK helper for obtaining the read-only host authorization
+ * client inside authored providers.
+ */
+export function Authorization(): AuthorizationClient {
+  const target = resolveAuthorizationSocketTarget();
+  const token = process.env[ENV_AUTHORIZATION_SOCKET_TOKEN]?.trim() ?? "";
+  if (
+    sharedAuthorizationTransport.client &&
+    sharedAuthorizationTransport.target === target &&
+    sharedAuthorizationTransport.token === token
+  ) {
+    return sharedAuthorizationTransport.client;
+  }
+
+  const client = new AuthorizationClient(target, token);
+  sharedAuthorizationTransport.target = target;
+  sharedAuthorizationTransport.token = token;
+  sharedAuthorizationTransport.client = client;
+  return client;
+}
+
+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: unsupported target scheme ${JSON.stringify(parsed.protocol.replace(/:$/, ""))}`,
+    );
+  }
+  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);
+  };
+}