@consciousclouds/conductor-sdk 0.1.0

package/dist/validate/index.js

@@ -0,0 +1,131 @@
+/**
+ * Runtime validation of the Conductor wire shapes (zod mirror of the JSON
+ * Schema).
+ *
+ * The JSON Schema under platform/contracts/conductor/v1/ is authoritative; this
+ * zod schema mirrors it for ergonomic in-process validation. Request envelopes
+ * and the SSE envelope are closed (`.strict()`); each event's `data` object is
+ * open (`.passthrough()`) so consumers ignore fields they don't know.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/** The frozen SSE event names, in contract order. */
+export const EVENT_NAMES = [
+    'started',
+    'delta',
+    'tool_start',
+    'tool_done',
+    'approval_required',
+    'completed',
+    'error',
+    'routed',
+];
+/** The capability string pattern, mirroring capability.schema.json. */
+export const capabilitySchema = z.string().regex(/^[a-z_]+\.[a-z_]+$/);
+export const turnRequestSchema = z
+    .object({
+    personality_id: z.string().min(1).optional(),
+    prompt: z.string().min(1),
+})
+    .strict();
+export const resolveRequestSchema = z
+    .object({
+    decision: z.enum(['approve', 'reject']),
+})
+    .strict();
+export const resolveResultSchema = z
+    .object({
+    approval_id: z.string(),
+    status: z.string(),
+    tool: z.string(),
+    result: z.record(z.unknown()).nullable(),
+    outcome: z.string(),
+})
+    .strict();
+// --- per-event data payloads (open: passthrough) -----------------------------
+const startedData = z
+    .object({ turn_id: z.string(), personality: z.string(), tier: z.string() })
+    .passthrough();
+const deltaData = z.object({ text: z.string() }).passthrough();
+const toolStartData = z
+    .object({ tool: z.string(), status: z.string().optional(), message: z.string().optional() })
+    .passthrough();
+const toolDoneData = z
+    .object({ tool: z.string(), status: z.string().optional(), message: z.string().optional() })
+    .passthrough();
+const approvalRequiredData = z
+    .object({
+    turn_id: z.string(),
+    approval_id: z.string(),
+    pending: z
+        .object({ tool_call_id: z.string(), tool: z.string() })
+        .passthrough(),
+})
+    .passthrough();
+const completedData = z
+    .object({
+    turn_id: z.string(),
+    calls: z.number(),
+    tool_calls: z.number(),
+    input_tokens: z.number(),
+    output_tokens: z.number(),
+    cost_usd: z.number(),
+})
+    .passthrough();
+const errorData = z.object({ code: z.string(), message: z.string() }).passthrough();
+const routedData = z
+    .object({
+    kind: z.enum(['navigation', 'action']),
+    target: z.string(),
+    mode: z.enum(['navigate', 'open-view', 'load-source']),
+    params: z.record(z.unknown()).optional(),
+    correlation_id: z.string().optional(),
+})
+    .passthrough();
+/** data payload schema keyed by event name. */
+export const EVENT_DATA_SCHEMAS = {
+    started: startedData,
+    delta: deltaData,
+    tool_start: toolStartData,
+    tool_done: toolDoneData,
+    approval_required: approvalRequiredData,
+    completed: completedData,
+    error: errorData,
+    routed: routedData,
+};
+/** The SSE envelope: a frozen event name plus its matching data payload. */
+export const sseEventSchema = z
+    .object({
+    event: z.enum(EVENT_NAMES),
+    data: z.record(z.unknown()),
+})
+    .strict();
+function toResult(parsed) {
+    if (parsed.success)
+        return { ok: true, data: parsed.data };
+    return {
+        ok: false,
+        errors: parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`),
+    };
+}
+/** Validate an unknown value as a TurnRequest. */
+export function validateTurnRequest(input) {
+    return toResult(turnRequestSchema.safeParse(input));
+}
+/** Validate an unknown value as a ResolveRequest. */
+export function validateResolveRequest(input) {
+    return toResult(resolveRequestSchema.safeParse(input));
+}
+/**
+ * Validate an SSE event's name + data. Returns ok=false when the name is not in
+ * the frozen set or the data does not match that event's payload schema.
+ */
+export function validateSseEvent(name, data) {
+    if (!EVENT_NAMES.includes(name)) {
+        return { ok: false, errors: [`event: unknown event name "${name}"`] };
+    }
+    const schema = EVENT_DATA_SCHEMAS[name];
+    return toResult(schema.safeParse(data));
+}
+//# sourceMappingURL=index.js.map

package/dist/validate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validate/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@consciousclouds/conductor-sdk",
+  "version": "0.1.0",
+  "description": "Conscious Clouds Conductor SDK — TurnRequest/SSE event/approval types, tool + personality + capability declaration types, and a thin Conductor client (streaming turn + approval resolve). Framework-agnostic, provider-agnostic. baseUrl is a configurable Conductor-compatible endpoint; the SDK never mints identity and never hard-codes a gateway URL.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/conductor-client.d.ts",
+      "import": "./dist/client/conductor-client.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js"
+    },
+    "./personalities": {
+      "types": "./dist/personalities.d.ts",
+      "import": "./dist/personalities.js"
+    },
+    "./capabilities": {
+      "types": "./dist/capabilities.d.ts",
+      "import": "./dist/capabilities.js"
+    },
+    "./validate": {
+      "types": "./dist/validate/index.d.ts",
+      "import": "./dist/validate/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run clean && bun run build && bun run type-check"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  }
+}