@kb-labs/host-agent-contracts 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,322 @@
+import { z } from 'zod';
+
+/** Token pair returned by Gateway /auth/token and /auth/refresh */
+declare const TokenPairSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    refreshToken: z.ZodString;
+    expiresIn: z.ZodNumber;
+    tokenType: z.ZodLiteral<"Bearer">;
+}, "strip", z.ZodTypeAny, {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    tokenType: "Bearer";
+}, {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    tokenType: "Bearer";
+}>;
+/** Execution configuration for Workspace Agent */
+declare const ExecutionConfigSchema: z.ZodObject<{
+    /** Execution mode: in-process (fast, trust) or subprocess (sandboxed) */
+    mode: z.ZodDefault<z.ZodEnum<["in-process", "subprocess"]>>;
+    /** Overall execution timeout in ms */
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    /** Plugin allowlist. Empty/undefined = all plugins allowed. */
+    allowedPlugins: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    mode: "in-process" | "subprocess";
+    timeoutMs: number;
+    allowedPlugins?: string[] | undefined;
+}, {
+    mode?: "in-process" | "subprocess" | undefined;
+    timeoutMs?: number | undefined;
+    allowedPlugins?: string[] | undefined;
+}>;
+/** Workspace entry — describes a project directory managed by this agent */
+declare const WorkspaceEntrySchema: z.ZodObject<{
+    /** Logical workspace ID */
+    workspaceId: z.ZodString;
+    /** Absolute path to project root */
+    path: z.ZodString;
+    /** Hash(origin URL + root commit) for repo identity */
+    repoFingerprint: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    workspaceId: string;
+    repoFingerprint?: string | undefined;
+}, {
+    path: string;
+    workspaceId: string;
+    repoFingerprint?: string | undefined;
+}>;
+/**
+ * ~/.kb/agent.json — persisted on the developer's machine after `kb workspace register`
+ */
+declare const AgentConfigSchema: z.ZodObject<{
+    clientId: z.ZodString;
+    clientSecret: z.ZodString;
+    hostId: z.ZodString;
+    gatewayUrl: z.ZodEffects<z.ZodString, string, string>;
+    /** X25519 private key, base64url — never leaves the machine */
+    privateKey: z.ZodOptional<z.ZodString>;
+    /** X25519 public key, base64url — sent to Gateway on hello */
+    publicKey: z.ZodOptional<z.ZodString>;
+    namespaceId: z.ZodDefault<z.ZodString>;
+    /** Host type: local (developer laptop) or cloud (provisioned container) */
+    hostType: z.ZodDefault<z.ZodEnum<["local", "cloud"]>>;
+    /**
+     * Explicit list of workspace paths the agent is allowed to access.
+     * Principle of least privilege: no access outside these paths.
+     */
+    workspacePaths: z.ZodArray<z.ZodString, "many">;
+    /** Structured workspace entries (optional, enriches workspacePaths) */
+    workspaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** Logical workspace ID */
+        workspaceId: z.ZodString;
+        /** Absolute path to project root */
+        path: z.ZodString;
+        /** Hash(origin URL + root commit) for repo identity */
+        repoFingerprint: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        workspaceId: string;
+        repoFingerprint?: string | undefined;
+    }, {
+        path: string;
+        workspaceId: string;
+        repoFingerprint?: string | undefined;
+    }>, "many">>;
+    /** Execution configuration for plugin execution capability */
+    execution: z.ZodDefault<z.ZodObject<{
+        /** Execution mode: in-process (fast, trust) or subprocess (sandboxed) */
+        mode: z.ZodDefault<z.ZodEnum<["in-process", "subprocess"]>>;
+        /** Overall execution timeout in ms */
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        /** Plugin allowlist. Empty/undefined = all plugins allowed. */
+        allowedPlugins: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "in-process" | "subprocess";
+        timeoutMs: number;
+        allowedPlugins?: string[] | undefined;
+    }, {
+        mode?: "in-process" | "subprocess" | undefined;
+        timeoutMs?: number | undefined;
+        allowedPlugins?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    clientId: string;
+    clientSecret: string;
+    hostId: string;
+    gatewayUrl: string;
+    namespaceId: string;
+    hostType: "local" | "cloud";
+    workspacePaths: string[];
+    execution: {
+        mode: "in-process" | "subprocess";
+        timeoutMs: number;
+        allowedPlugins?: string[] | undefined;
+    };
+    privateKey?: string | undefined;
+    publicKey?: string | undefined;
+    workspaces?: {
+        path: string;
+        workspaceId: string;
+        repoFingerprint?: string | undefined;
+    }[] | undefined;
+}, {
+    clientId: string;
+    clientSecret: string;
+    hostId: string;
+    gatewayUrl: string;
+    workspacePaths: string[];
+    privateKey?: string | undefined;
+    publicKey?: string | undefined;
+    namespaceId?: string | undefined;
+    hostType?: "local" | "cloud" | undefined;
+    workspaces?: {
+        path: string;
+        workspaceId: string;
+        repoFingerprint?: string | undefined;
+    }[] | undefined;
+    execution?: {
+        mode?: "in-process" | "subprocess" | undefined;
+        timeoutMs?: number | undefined;
+        allowedPlugins?: string[] | undefined;
+    } | undefined;
+}>;
+type ExecutionConfig = z.infer<typeof ExecutionConfigSchema>;
+type WorkspaceEntry = z.infer<typeof WorkspaceEntrySchema>;
+type AgentConfig = z.infer<typeof AgentConfigSchema>;
+
+declare const CapabilitySchema: z.ZodEnum<["filesystem", "git", "editor-context"]>;
+type Capability = z.infer<typeof CapabilitySchema>;
+/** A call dispatched from Gateway → Host Agent for a capability */
+declare const CapabilityCallSchema: z.ZodObject<{
+    type: z.ZodLiteral<"call">;
+    requestId: z.ZodString;
+    adapter: z.ZodString;
+    method: z.ZodString;
+    args: z.ZodArray<z.ZodUnknown, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "call";
+    requestId: string;
+    adapter: string;
+    method: string;
+    args: unknown[];
+}, {
+    type: "call";
+    requestId: string;
+    adapter: string;
+    method: string;
+    args: unknown[];
+}>;
+type CapabilityCall = z.infer<typeof CapabilityCallSchema>;
+declare const CapabilityResultSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    data: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    requestId: string;
+    data?: unknown;
+}, {
+    requestId: string;
+    data?: unknown;
+}>;
+type CapabilityResult = z.infer<typeof CapabilityResultSchema>;
+declare const CapabilityErrorSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    code: z.ZodString;
+    message: z.ZodString;
+    retryable: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    requestId: string;
+    retryable: boolean;
+}, {
+    code: string;
+    message: string;
+    requestId: string;
+    retryable?: boolean | undefined;
+}>;
+type CapabilityError = z.infer<typeof CapabilityErrorSchema>;
+
+/**
+ * IPC protocol over Unix socket (~/.kb/agent.sock)
+ * Used by CLI/Studio to talk to the local daemon.
+ */
+declare const IpcExecuteRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"execute">;
+    requestId: z.ZodString;
+    command: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    stream: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "execute";
+    requestId: string;
+    command: string;
+    stream: boolean;
+    params?: Record<string, unknown> | undefined;
+}, {
+    type: "execute";
+    requestId: string;
+    command: string;
+    params?: Record<string, unknown> | undefined;
+    stream?: boolean | undefined;
+}>;
+type IpcExecuteRequest = z.infer<typeof IpcExecuteRequestSchema>;
+declare const IpcEventMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"event">;
+    requestId: z.ZodString;
+    data: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: "event";
+    requestId: string;
+    data?: unknown;
+}, {
+    type: "event";
+    requestId: string;
+    data?: unknown;
+}>;
+type IpcEventMessage = z.infer<typeof IpcEventMessageSchema>;
+declare const IpcDoneMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"done">;
+    requestId: z.ZodString;
+    result: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: "done";
+    requestId: string;
+    result?: unknown;
+}, {
+    type: "done";
+    requestId: string;
+    result?: unknown;
+}>;
+type IpcDoneMessage = z.infer<typeof IpcDoneMessageSchema>;
+declare const IpcErrorMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    requestId: z.ZodString;
+    code: z.ZodString;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    type: "error";
+    requestId: string;
+}, {
+    code: string;
+    message: string;
+    type: "error";
+    requestId: string;
+}>;
+type IpcErrorMessage = z.infer<typeof IpcErrorMessageSchema>;
+declare const IpcCancelRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"cancel">;
+    executionId: z.ZodString;
+    reason: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "cancel";
+    executionId: string;
+    reason: string;
+}, {
+    type: "cancel";
+    executionId: string;
+    reason?: string | undefined;
+}>;
+type IpcCancelRequest = z.infer<typeof IpcCancelRequestSchema>;
+declare const IpcStatusRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"status">;
+}, "strip", z.ZodTypeAny, {
+    type: "status";
+}, {
+    type: "status";
+}>;
+type IpcStatusRequest = z.infer<typeof IpcStatusRequestSchema>;
+declare const IpcStatusResponseSchema: z.ZodObject<{
+    type: z.ZodLiteral<"status">;
+    connected: z.ZodBoolean;
+    hostId: z.ZodOptional<z.ZodString>;
+    gatewayUrl: z.ZodOptional<z.ZodString>;
+    latencyMs: z.ZodOptional<z.ZodNumber>;
+    reconnecting: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "status";
+    connected: boolean;
+    reconnecting: boolean;
+    hostId?: string | undefined;
+    gatewayUrl?: string | undefined;
+    latencyMs?: number | undefined;
+}, {
+    type: "status";
+    connected: boolean;
+    hostId?: string | undefined;
+    gatewayUrl?: string | undefined;
+    latencyMs?: number | undefined;
+    reconnecting?: boolean | undefined;
+}>;
+type IpcStatusResponse = z.infer<typeof IpcStatusResponseSchema>;
+type IpcRequest = IpcExecuteRequest | IpcCancelRequest | IpcStatusRequest;
+type IpcResponse = IpcEventMessage | IpcDoneMessage | IpcErrorMessage | IpcStatusResponse;
+
+export { type AgentConfig, AgentConfigSchema, type Capability, type CapabilityCall, CapabilityCallSchema, type CapabilityError, CapabilityErrorSchema, type CapabilityResult, CapabilityResultSchema, CapabilitySchema, type ExecutionConfig, ExecutionConfigSchema, type IpcCancelRequest, IpcCancelRequestSchema, type IpcDoneMessage, IpcDoneMessageSchema, type IpcErrorMessage, IpcErrorMessageSchema, type IpcEventMessage, IpcEventMessageSchema, type IpcExecuteRequest, IpcExecuteRequestSchema, type IpcRequest, type IpcResponse, type IpcStatusRequest, IpcStatusRequestSchema, type IpcStatusResponse, IpcStatusResponseSchema, TokenPairSchema, type WorkspaceEntry, WorkspaceEntrySchema };

package/dist/index.js

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+
+// src/config.ts
+var TokenPairSchema = z.object({
+  accessToken: z.string().min(1),
+  refreshToken: z.string().min(1),
+  expiresIn: z.number().positive(),
+  tokenType: z.literal("Bearer")
+});
+var ExecutionConfigSchema = z.object({
+  /** Execution mode: in-process (fast, trust) or subprocess (sandboxed) */
+  mode: z.enum(["in-process", "subprocess"]).default("in-process"),
+  /** Overall execution timeout in ms */
+  timeoutMs: z.number().positive().default(12e4),
+  /** Plugin allowlist. Empty/undefined = all plugins allowed. */
+  allowedPlugins: z.array(z.string()).optional()
+});
+var WorkspaceEntrySchema = z.object({
+  /** Logical workspace ID */
+  workspaceId: z.string(),
+  /** Absolute path to project root */
+  path: z.string(),
+  /** Hash(origin URL + root commit) for repo identity */
+  repoFingerprint: z.string().optional()
+});
+var AgentConfigSchema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  hostId: z.string(),
+  gatewayUrl: z.string().url().refine(
+    (url) => url.startsWith("https://") || url.startsWith("http://localhost") || url.startsWith("http://127.0.0.1"),
+    { message: "gatewayUrl must use HTTPS (HTTP only allowed for localhost in dev)" }
+  ),
+  /** X25519 private key, base64url — never leaves the machine */
+  privateKey: z.string().optional(),
+  /** X25519 public key, base64url — sent to Gateway on hello */
+  publicKey: z.string().optional(),
+  namespaceId: z.string().default("default"),
+  /** Host type: local (developer laptop) or cloud (provisioned container) */
+  hostType: z.enum(["local", "cloud"]).default("local"),
+  /**
+   * Explicit list of workspace paths the agent is allowed to access.
+   * Principle of least privilege: no access outside these paths.
+   */
+  workspacePaths: z.array(z.string()).min(1),
+  /** Structured workspace entries (optional, enriches workspacePaths) */
+  workspaces: z.array(WorkspaceEntrySchema).optional(),
+  /** Execution configuration for plugin execution capability */
+  execution: ExecutionConfigSchema.default({})
+});
+var CapabilitySchema = z.enum(["filesystem", "git", "editor-context"]);
+var CapabilityCallSchema = z.object({
+  type: z.literal("call"),
+  requestId: z.string(),
+  adapter: z.string(),
+  // 'filesystem' | 'git'
+  method: z.string(),
+  args: z.array(z.unknown())
+});
+var CapabilityResultSchema = z.object({
+  requestId: z.string(),
+  data: z.unknown()
+});
+var CapabilityErrorSchema = z.object({
+  requestId: z.string(),
+  code: z.string(),
+  message: z.string(),
+  retryable: z.boolean().default(false)
+});
+var IpcExecuteRequestSchema = z.object({
+  type: z.literal("execute"),
+  requestId: z.string(),
+  command: z.string(),
+  params: z.record(z.unknown()).optional(),
+  stream: z.boolean().default(false)
+});
+var IpcEventMessageSchema = z.object({
+  type: z.literal("event"),
+  requestId: z.string(),
+  data: z.unknown()
+});
+var IpcDoneMessageSchema = z.object({
+  type: z.literal("done"),
+  requestId: z.string(),
+  result: z.unknown()
+});
+var IpcErrorMessageSchema = z.object({
+  type: z.literal("error"),
+  requestId: z.string(),
+  code: z.string(),
+  message: z.string()
+});
+var IpcCancelRequestSchema = z.object({
+  type: z.literal("cancel"),
+  executionId: z.string(),
+  reason: z.string().default("user")
+});
+var IpcStatusRequestSchema = z.object({
+  type: z.literal("status")
+});
+var IpcStatusResponseSchema = z.object({
+  type: z.literal("status"),
+  connected: z.boolean(),
+  hostId: z.string().optional(),
+  gatewayUrl: z.string().optional(),
+  latencyMs: z.number().optional(),
+  reconnecting: z.boolean().default(false)
+});
+
+export { AgentConfigSchema, CapabilityCallSchema, CapabilityErrorSchema, CapabilityResultSchema, CapabilitySchema, ExecutionConfigSchema, IpcCancelRequestSchema, IpcDoneMessageSchema, IpcErrorMessageSchema, IpcEventMessageSchema, IpcExecuteRequestSchema, IpcStatusRequestSchema, IpcStatusResponseSchema, TokenPairSchema, WorkspaceEntrySchema };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts","../src/capability.ts","../src/ipc.ts"],"names":["z"],"mappings":"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","file":"index.js","sourcesContent":["import { z } from 'zod';\n\n/** Token pair returned by Gateway /auth/token and /auth/refresh */\nexport const TokenPairSchema = z.object({\n  accessToken: z.string().min(1),\n  refreshToken: z.string().min(1),\n  expiresIn: z.number().positive(),\n  tokenType: z.literal('Bearer'),\n});\n\n/** Execution configuration for Workspace Agent */\nexport const ExecutionConfigSchema = z.object({\n  /** Execution mode: in-process (fast, trust) or subprocess (sandboxed) */\n  mode: z.enum(['in-process', 'subprocess']).default('in-process'),\n  /** Overall execution timeout in ms */\n  timeoutMs: z.number().positive().default(120_000),\n  /** Plugin allowlist. Empty/undefined = all plugins allowed. */\n  allowedPlugins: z.array(z.string()).optional(),\n});\n\n/** Workspace entry — describes a project directory managed by this agent */\nexport const WorkspaceEntrySchema = z.object({\n  /** Logical workspace ID */\n  workspaceId: z.string(),\n  /** Absolute path to project root */\n  path: z.string(),\n  /** Hash(origin URL + root commit) for repo identity */\n  repoFingerprint: z.string().optional(),\n});\n\n/**\n * ~/.kb/agent.json — persisted on the developer's machine after `kb workspace register`\n */\nexport const AgentConfigSchema = z.object({\n  clientId: z.string(),\n  clientSecret: z.string(),\n  hostId: z.string(),\n  gatewayUrl: z.string().url().refine(\n    (url) => url.startsWith('https://') || url.startsWith('http://localhost') || url.startsWith('http://127.0.0.1'),\n    { message: 'gatewayUrl must use HTTPS (HTTP only allowed for localhost in dev)' },\n  ),\n  /** X25519 private key, base64url — never leaves the machine */\n  privateKey: z.string().optional(),\n  /** X25519 public key, base64url — sent to Gateway on hello */\n  publicKey: z.string().optional(),\n  namespaceId: z.string().default('default'),\n  /** Host type: local (developer laptop) or cloud (provisioned container) */\n  hostType: z.enum(['local', 'cloud']).default('local'),\n  /**\n   * Explicit list of workspace paths the agent is allowed to access.\n   * Principle of least privilege: no access outside these paths.\n   */\n  workspacePaths: z.array(z.string()).min(1),\n  /** Structured workspace entries (optional, enriches workspacePaths) */\n  workspaces: z.array(WorkspaceEntrySchema).optional(),\n  /** Execution configuration for plugin execution capability */\n  execution: ExecutionConfigSchema.default({}),\n});\n\nexport type ExecutionConfig = z.infer<typeof ExecutionConfigSchema>;\nexport type WorkspaceEntry = z.infer<typeof WorkspaceEntrySchema>;\nexport type AgentConfig = z.infer<typeof AgentConfigSchema>;\n","import { z } from 'zod';\n\nexport const CapabilitySchema = z.enum(['filesystem', 'git', 'editor-context']);\nexport type Capability = z.infer<typeof CapabilitySchema>;\n\n/** A call dispatched from Gateway → Host Agent for a capability */\nexport const CapabilityCallSchema = z.object({\n  type: z.literal('call'),\n  requestId: z.string(),\n  adapter: z.string(),   // 'filesystem' | 'git'\n  method: z.string(),\n  args: z.array(z.unknown()),\n});\nexport type CapabilityCall = z.infer<typeof CapabilityCallSchema>;\n\nexport const CapabilityResultSchema = z.object({\n  requestId: z.string(),\n  data: z.unknown(),\n});\nexport type CapabilityResult = z.infer<typeof CapabilityResultSchema>;\n\nexport const CapabilityErrorSchema = z.object({\n  requestId: z.string(),\n  code: z.string(),\n  message: z.string(),\n  retryable: z.boolean().default(false),\n});\nexport type CapabilityError = z.infer<typeof CapabilityErrorSchema>;\n","import { z } from 'zod';\n\n/**\n * IPC protocol over Unix socket (~/.kb/agent.sock)\n * Used by CLI/Studio to talk to the local daemon.\n */\n\nexport const IpcExecuteRequestSchema = z.object({\n  type: z.literal('execute'),\n  requestId: z.string(),\n  command: z.string(),\n  params: z.record(z.unknown()).optional(),\n  stream: z.boolean().default(false),\n});\nexport type IpcExecuteRequest = z.infer<typeof IpcExecuteRequestSchema>;\n\nexport const IpcEventMessageSchema = z.object({\n  type: z.literal('event'),\n  requestId: z.string(),\n  data: z.unknown(),\n});\nexport type IpcEventMessage = z.infer<typeof IpcEventMessageSchema>;\n\nexport const IpcDoneMessageSchema = z.object({\n  type: z.literal('done'),\n  requestId: z.string(),\n  result: z.unknown(),\n});\nexport type IpcDoneMessage = z.infer<typeof IpcDoneMessageSchema>;\n\nexport const IpcErrorMessageSchema = z.object({\n  type: z.literal('error'),\n  requestId: z.string(),\n  code: z.string(),\n  message: z.string(),\n});\nexport type IpcErrorMessage = z.infer<typeof IpcErrorMessageSchema>;\n\nexport const IpcCancelRequestSchema = z.object({\n  type: z.literal('cancel'),\n  executionId: z.string(),\n  reason: z.string().default('user'),\n});\nexport type IpcCancelRequest = z.infer<typeof IpcCancelRequestSchema>;\n\nexport const IpcStatusRequestSchema = z.object({\n  type: z.literal('status'),\n});\nexport type IpcStatusRequest = z.infer<typeof IpcStatusRequestSchema>;\n\nexport const IpcStatusResponseSchema = z.object({\n  type: z.literal('status'),\n  connected: z.boolean(),\n  hostId: z.string().optional(),\n  gatewayUrl: z.string().optional(),\n  latencyMs: z.number().optional(),\n  reconnecting: z.boolean().default(false),\n});\nexport type IpcStatusResponse = z.infer<typeof IpcStatusResponseSchema>;\n\nexport type IpcRequest = IpcExecuteRequest | IpcCancelRequest | IpcStatusRequest;\nexport type IpcResponse = IpcEventMessage | IpcDoneMessage | IpcErrorMessage | IpcStatusResponse;\n"]}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kb-labs/host-agent-contracts",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run -c ../../vitest.config.ts --passWithNoTests",
+    "test:watch": "vitest -c ../../vitest.config.ts --passWithNoTests"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "rimraf": "^6",
+    "tsup": "^8.5.0",
+    "vitest": "^3.2.4"
+  }
+}