@oscharko-dev/keiko-server 0.2.7 → 0.2.9

package/dist/run-handlers.js

@@ -5,17 +5,19 @@
 // redacted final report projection (or status:"running"); apply is the ONLY write path, re-invoking
 // the same workflow with apply:true through the existing gated path. No model is ever called
 // directly; no guard is reimplemented; no secret reaches any response (live payloads are redacted).
-import { randomUUID } from "node:crypto";
 import { parseRunRequest } from "./run-request.js";
 import { startRun, applyRun } from "./run-engine.js";
 import { ActiveRunLimitError } from "./runs.js";
 import { SSE_HEADERS, writeEvent, readyMessage } from "./sse.js";
 import { errorBody, STREAMING } from "./routes.js";
 import { currentRedactionSecrets } from "./deps.js";
-import { createAuditRedactor } from "@oscharko-dev/keiko-evidence";
+import { VOICE_TRANSCRIPT_SCHEMA_VERSION, } from "@oscharko-dev/keiko-contracts";
+import { validateWorkflowHandoffRequest } from "@oscharko-dev/keiko-contracts/workflow-handoff";
 import { WorkspaceError } from "@oscharko-dev/keiko-workspace";
-import { UiStoreError } from "./store/index.js";
-import { memoryCaptureCustomerMatchers } from "./memory-capture-policy.js";
+import { approvalTokenInputFor, createApprovalToken } from "./governed-workflow.js";
+import { isVoiceDictationCapable, isVoiceRealtimeCapable } from "./read-handlers.js";
+import { evaluateSpokenActionGovernance } from "./voice-action-governance.js";
+import { resolveRegisteredOrManagedWorkspaceRoot } from "./task-workspace/authorization.js";
 const MAX_BODY_BYTES = 1_000_000;
 const VERIFY_NOOP_MODEL = {
     call: () => Promise.reject(new Error("verify runs must not call the model")),
@@ -64,7 +66,7 @@ function readBody(req) {
 // directories. Returns a RouteResult to return, or null when the check passes.
 function rejectUnregisteredWorkspace(parsed, deps) {
     const root = typeof parsed.input.workspaceRoot === "string" ? parsed.input.workspaceRoot : "";
-    const registered = deps.store.listProjects().some((p) => p.path === root);
+    const registered = resolveRegisteredOrManagedWorkspaceRoot(deps, root) !== undefined;
     return registered
         ? null
         : {
@@ -75,111 +77,68 @@ function rejectUnregisteredWorkspace(parsed, deps) {
 function resolveRunModel(parsed, deps) {
     return parsed.kind === "verify" ? VERIFY_NOOP_MODEL : deps.modelPortFactory(parsed.modelId);
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function requireBodyString(body, name) {
-    const value = body[name];
-    if (typeof value !== "string" || value.length === 0) {
-        return { status: 400, body: errorBody("BAD_REQUEST", `Field "${name}" is required.`) };
+function validateTextGovernedHandoff(parsed) {
+    if (parsed.governedHandoff === undefined || parsed.governedHandoffVoiceOrigin !== undefined) {
+        return null;
     }
-    return value;
-}
-function requireBodyNumber(body, name) {
-    const value = body[name];
-    if (typeof value !== "number" || !Number.isFinite(value)) {
+    const validation = validateWorkflowHandoffRequest(parsed.governedHandoff);
+    if (!validation.ok) {
+        return { status: 400, body: errorBody("BAD_REQUEST", validation.reasons.join("; ")) };
+    }
+    const expectedToken = createApprovalToken(approvalTokenInputFor(parsed.governedHandoff));
+    if (parsed.governedHandoff.userApprovalToken !== expectedToken) {
         return {
             status: 400,
-            body: errorBody("BAD_REQUEST", `Field "${name}" must be a finite number.`),
+            body: errorBody("BAD_REQUEST", "governedHandoff approval token does not match the request."),
         };
     }
-    return value;
+    return null;
 }
-function requireBodyRecord(body, name) {
-    const value = body[name];
-    if (!isRecord(value)) {
-        return { status: 400, body: errorBody("BAD_REQUEST", `Field "${name}" must be an object.`) };
-    }
-    return value;
-}
-function parseJsonRecord(raw) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return { status: 400, body: errorBody("BAD_REQUEST", "Request body is not valid JSON.") };
+function serverTrustedVoiceProfile(deps) {
+    if (isVoiceRealtimeCapable(deps)) {
+        return "full-realtime";
     }
-    if (!isRecord(parsed)) {
-        return { status: 400, body: errorBody("BAD_REQUEST", "Request body must be a JSON object.") };
+    if (isVoiceDictationCapable(deps)) {
+        return "speech-to-text";
     }
-    return parsed;
+    return "none";
 }
-function isRouteResult(value) {
-    return isRecord(value) && typeof value.status === "number" && "body" in value;
-}
-function chatBelongsToProject(deps, projectPath, chatId) {
-    return deps.store.listChats(projectPath).some((chat) => chat.id === chatId);
+function committedProjectionFor(origin) {
+    return {
+        schemaVersion: VOICE_TRANSCRIPT_SCHEMA_VERSION,
+        segments: [],
+        text: origin.committedText,
+        segmentCount: origin.committedSegments,
+    };
 }
-function runSummaryDiscriminator(request) {
-    if (request.kind === "unit-tests") {
-        return { workflowId: "unit-test-generation", taskType: undefined };
-    }
-    if (request.kind === "bug-investigation") {
-        return { workflowId: "bug-investigation", taskType: undefined };
-    }
-    if (request.kind === "explain-plan") {
-        return { workflowId: undefined, taskType: "explain-plan" };
+function applyVoiceGovernance(parsed, deps) {
+    if (parsed.governedHandoffVoiceOrigin === undefined) {
+        const invalidTextHandoff = validateTextGovernedHandoff(parsed);
+        return invalidTextHandoff ?? parsed;
+    }
+    if (parsed.governedHandoff === undefined) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "voiceOrigin requires governedHandoff.") };
+    }
+    const trustedProfile = serverTrustedVoiceProfile(deps);
+    const decision = evaluateSpokenActionGovernance({
+        projection: committedProjectionFor(parsed.governedHandoffVoiceOrigin),
+        profile: trustedProfile,
+        turnIndex: parsed.governedHandoffVoiceOrigin.turnIndex,
+        source: parsed.governedHandoffVoiceOrigin.source,
+        request: parsed.governedHandoff,
+        providedConfirmationDigest: parsed.governedHandoffVoiceOrigin.confirmationDigest,
+    });
+    if (!decision.allowed) {
+        return { status: 403, body: errorBody("VOICE_ACTION_DENIED", decision.reason) };
     }
-    return { workflowId: undefined, taskType: "verify" };
-}
-function buildChatRunMessages(body, request, chatId, runId) {
-    const user = requireBodyRecord(body, "user");
-    if (isRouteResult(user))
-        return user;
-    const summary = requireBodyRecord(body, "summary");
-    if (isRouteResult(summary))
-        return summary;
-    const userContent = requireBodyString(user, "content");
-    if (typeof userContent !== "string")
-        return userContent;
-    const userTimestamp = requireBodyNumber(user, "timestamp");
-    if (typeof userTimestamp !== "number")
-        return userTimestamp;
-    const summaryContent = requireBodyString(summary, "content");
-    if (typeof summaryContent !== "string")
-        return summaryContent;
-    const summaryTimestamp = requireBodyNumber(summary, "timestamp");
-    if (typeof summaryTimestamp !== "number")
-        return summaryTimestamp;
-    const discriminator = runSummaryDiscriminator(request);
-    return [
-        {
-            chatId,
-            role: "user",
-            content: userContent,
-            timestamp: userTimestamp,
-            runId: undefined,
-            workflowId: undefined,
-            workflowStatus: undefined,
-            shortResult: undefined,
-            taskType: undefined,
-        },
-        {
-            chatId,
-            role: "system",
-            content: summaryContent,
-            timestamp: summaryTimestamp,
-            runId,
-            workflowId: discriminator.workflowId,
-            workflowStatus: "running",
-            shortResult: undefined,
-            taskType: discriminator.taskType,
-        },
-    ];
+    return {
+        ...parsed,
+        governedHandoffVoiceOrigin: undefined,
+        governedHandoffVoiceAction: decision.audit,
+    };
 }
-function storeErrorResult(error) {
-    return { status: error.status, body: errorBody(error.code, error.message) };
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 // Static, path-safe message for workspace errors surfaced during run launch. The underlying
 // WorkspaceError messages may carry absolute paths — we never echo them (ADR-0005, CWE-209).
@@ -190,86 +149,6 @@ function workspaceRunErrorResult() {
         body: errorBody("WORKSPACE_UNAVAILABLE", WORKSPACE_RUN_ERROR_MESSAGE),
     };
 }
-function markSummaryFailed(deps, message, shortResult) {
-    try {
-        deps.store.updateMessage(message.id, { workflowStatus: "failed", shortResult });
-    }
-    catch {
-        // Best-effort compensation only. The original start error remains the response source.
-    }
-}
-function parseChatRunEnvelope(raw, deps) {
-    const body = parseJsonRecord(raw);
-    if (isRouteResult(body))
-        return body;
-    const chatId = requireBodyString(body, "chatId");
-    if (isRouteResult(chatId))
-        return chatId;
-    const projectPath = requireBodyString(body, "projectPath");
-    if (isRouteResult(projectPath))
-        return projectPath;
-    if (!chatBelongsToProject(deps, projectPath, chatId)) {
-        return { status: 404, body: errorBody("NOT_FOUND", "Chat not found.") };
-    }
-    const runBody = requireBodyRecord(body, "run");
-    if (isRouteResult(runBody))
-        return runBody;
-    return { body, chatId, projectPath, runBody };
-}
-function validateChatRunRequest(runBody, deps) {
-    const parsed = parseRunRequest(JSON.stringify(runBody));
-    if ("code" in parsed) {
-        return { status: 400, body: errorBody(parsed.code, parsed.message) };
-    }
-    const unregistered = rejectUnregisteredWorkspace(parsed, deps);
-    if (unregistered !== null)
-        return unregistered;
-    const model = resolveRunModel(parsed, deps);
-    return model === undefined
-        ? { status: 400, body: errorBody("NO_MODEL", "No model provider is configured.") }
-        : { request: parsed, model };
-}
-function engineContextFor(deps, request, model) {
-    return {
-        request,
-        model,
-        registry: deps.registry,
-        evidence: {
-            store: deps.evidenceStore,
-            env: deps.env,
-            additionalSecrets: currentRedactionSecrets(deps),
-        },
-        memoryVault: deps.memoryVault,
-        memoryAuditRedactString: createAuditRedactor({ additionalSecrets: currentRedactionSecrets(deps) }, deps.env),
-        memoryCustomerIdentifierMatchers: memoryCaptureCustomerMatchers(deps),
-    };
-}
-function persistChatRunMessages(deps, envelope, request, runId) {
-    const messagesInput = buildChatRunMessages(envelope.body, request, envelope.chatId, runId);
-    if (isRouteResult(messagesInput))
-        return messagesInput;
-    try {
-        return deps.store.createMessages(messagesInput);
-    }
-    catch (error) {
-        if (error instanceof UiStoreError)
-            return storeErrorResult(error);
-        throw error;
-    }
-}
-function startPersistedChatRun(deps, request, model, runId, messages) {
-    try {
-        const run = startRun(engineContextFor(deps, request, model), deps.redactor, { runId });
-        return { status: 202, body: { run, messages } };
-    }
-    catch (error) {
-        const summary = messages[1];
-        if (summary !== undefined) {
-            markSummaryFailed(deps, summary, "Run could not be started.");
-        }
-        return mapRunStartError(error);
-    }
-}
 function mapRunStartError(error) {
     if (error instanceof ActiveRunLimitError) {
         return { status: 429, body: errorBody("TOO_MANY_RUNS", "The active run limit is reached.") };
@@ -298,16 +177,20 @@ export async function handleCreateRun(ctx, deps) {
     if ("code" in parsed) {
         return { status: 400, body: errorBody(parsed.code, parsed.message) };
     }
-    const unregistered = rejectUnregisteredWorkspace(parsed, deps);
+    const governed = applyVoiceGovernance(parsed, deps);
+    if ("status" in governed) {
+        return governed;
+    }
+    const unregistered = rejectUnregisteredWorkspace(governed, deps);
     if (unregistered !== null) {
         return unregistered;
     }
-    const model = resolveRunModel(parsed, deps);
+    const model = resolveRunModel(governed, deps);
     if (model === undefined) {
         return { status: 400, body: errorBody("NO_MODEL", "No model provider is configured.") };
     }
     const engineCtx = {
-        request: parsed,
+        request: governed,
         model,
         registry: deps.registry,
         evidence: {
@@ -324,36 +207,6 @@ export async function handleCreateRun(ctx, deps) {
         return mapRunStartError(error);
     }
 }
-// Route — POST /api/chats/runs. Composer-specific path that makes Issue #66's chat invariant
-// explicit: a successful workflow launch first reserves a runId and persists exactly one user
-// message plus one system run summary, then starts the run with that reserved runId. If persistence
-// fails, no run is started; if the start is refused, the summary is terminalized as failed.
-export async function handleCreateChatRun(ctx, deps) {
-    let raw;
-    try {
-        raw = await readBody(ctx.req);
-    }
-    catch (error) {
-        if (error instanceof BodyTooLargeError) {
-            return {
-                status: 413,
-                body: errorBody("PAYLOAD_TOO_LARGE", "Request body exceeds the size limit."),
-            };
-        }
-        throw error;
-    }
-    const envelope = parseChatRunEnvelope(raw, deps);
-    if (isRouteResult(envelope))
-        return envelope;
-    const validated = validateChatRunRequest(envelope.runBody, deps);
-    if (isRouteResult(validated))
-        return validated;
-    const runId = randomUUID();
-    const messages = persistChatRunMessages(deps, envelope, validated.request, runId);
-    if (isRouteResult(messages))
-        return messages;
-    return startPersistedChatRun(deps, validated.request, validated.model, runId, messages);
-}
 function lastEventId(req) {
     const header = req.headers["last-event-id"];
     const value = Array.isArray(header) ? header[0] : header;

package/dist/run-request.d.ts

@@ -1,5 +1,14 @@
+import { type SpokenActionAuditRecord, type VoiceProfile, type VoiceTranscriptSource } from "@oscharko-dev/keiko-contracts";
 import type { WorkflowHandoffRequest } from "@oscharko-dev/keiko-contracts/workflow-handoff";
 export type RunKind = "unit-tests" | "bug-investigation" | "explain-plan" | "verify";
+export interface RunVoiceOrigin {
+    readonly profile: VoiceProfile;
+    readonly turnIndex: number;
+    readonly source: VoiceTranscriptSource;
+    readonly committedSegments: number;
+    readonly committedText: string;
+    readonly confirmationDigest: string | undefined;
+}
 export interface RunRequest {
     readonly kind: RunKind;
     readonly modelId: string;
@@ -8,6 +17,8 @@ export interface RunRequest {
     readonly limits: Record<string, unknown> | undefined;
     readonly governedHandoff?: WorkflowHandoffRequest | undefined;
     readonly governedHandoffSourceGroundedRunId?: string | undefined;
+    readonly governedHandoffVoiceOrigin?: RunVoiceOrigin | undefined;
+    readonly governedHandoffVoiceAction?: SpokenActionAuditRecord | undefined;
 }
 export interface RunRequestError {
     readonly code: "BAD_REQUEST";

package/dist/run-request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-request.d.ts","sourceRoot":"","sources":["../src/run-request.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gDAAgD,CAAC;AAE7F,MAAM,MAAM,OAAO,GAAG,YAAY,GAAG,mBAAmB,GAAG,cAAc,GAAG,QAAQ,CAAC;AAErF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAExB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAExC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAErD,QAAQ,CAAC,eAAe,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,kCAAkC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClE;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AA4ND,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,eAAe,CAsCzE"}
+{"version":3,"file":"run-request.d.ts","sourceRoot":"","sources":["../src/run-request.ts"],"names":[],"mappings":"AASA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC3B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gDAAgD,CAAC;AAE7F,MAAM,MAAM,OAAO,GAAG,YAAY,GAAG,mBAAmB,GAAG,cAAc,GAAG,QAAQ,CAAC;AAErF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;CACjD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAExB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAExC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAErD,QAAQ,CAAC,eAAe,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,kCAAkC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAGjE,QAAQ,CAAC,0BAA0B,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IAGjE,QAAQ,CAAC,0BAA0B,CAAC,EAAE,uBAAuB,GAAG,SAAS,CAAC;CAC3E;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAubD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,eAAe,CAczE"}

package/dist/run-request.js

@@ -6,9 +6,107 @@
 // the gated apply route (D8). The deeper guards (`isSensitivePath`, patch limits, target validation)
 // are enforced by the workflow/harness entry points the engine calls; the BFF never reimplements
 // them.
+import {} from "@oscharko-dev/keiko-contracts";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+const VOICE_PROFILES = [
+    "none",
+    "speech-to-text",
+    "speech-output",
+    "full-realtime",
+];
+const VOICE_TRANSCRIPT_SOURCES = ["dictation", "realtime"];
+const MAX_VOICE_COMMITTED_TEXT_CHARS = 8192;
+const MAX_VOICE_TURN_INDEX = 1_000_000;
+const MAX_VOICE_COMMITTED_SEGMENTS = 10_000;
+const CONFIRMATION_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+function badRequest(message) {
+    return { code: "BAD_REQUEST", message };
+}
+function isRunRequestError(value) {
+    return isRecord(value) && value.code === "BAD_REQUEST" && typeof value.message === "string";
+}
+function isVoiceProfile(value) {
+    return typeof value === "string" && VOICE_PROFILES.includes(value);
+}
+function isRunVoiceTranscriptSource(value) {
+    return (typeof value === "string" && VOICE_TRANSCRIPT_SOURCES.includes(value));
+}
+function isBoundedNonNegativeInteger(value, max) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= max;
+}
+function parseOptionalString(body, name) {
+    const value = body[name];
+    if (value === undefined) {
+        return undefined;
+    }
+    return typeof value === "string"
+        ? value
+        : badRequest(`${name} must be a string when provided.`);
+}
+function parseConfirmationDigest(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || !CONFIRMATION_DIGEST_PATTERN.test(value)) {
+        return badRequest("voiceOrigin.confirmationDigest must be a 64-char lowercase sha256 hex.");
+    }
+    return value;
+}
+function parseVoiceOriginFields(value) {
+    if (!isVoiceProfile(value.profile)) {
+        return badRequest("voiceOrigin.profile is invalid.");
+    }
+    if (!isBoundedNonNegativeInteger(value.turnIndex, MAX_VOICE_TURN_INDEX)) {
+        return badRequest("voiceOrigin.turnIndex must be a bounded non-negative integer.");
+    }
+    if (!isRunVoiceTranscriptSource(value.source)) {
+        return badRequest("voiceOrigin.source is invalid.");
+    }
+    if (!isBoundedNonNegativeInteger(value.committedSegments, MAX_VOICE_COMMITTED_SEGMENTS)) {
+        return badRequest("voiceOrigin.committedSegments must be a bounded non-negative integer.");
+    }
+    if (typeof value.committedText !== "string" ||
+        value.committedText.length > MAX_VOICE_COMMITTED_TEXT_CHARS) {
+        return badRequest("voiceOrigin.committedText must be a string within the size limit.");
+    }
+    const confirmationDigest = parseConfirmationDigest(value.confirmationDigest);
+    if (typeof confirmationDigest === "object") {
+        return confirmationDigest;
+    }
+    return {
+        profile: value.profile,
+        turnIndex: value.turnIndex,
+        source: value.source,
+        committedSegments: value.committedSegments,
+        committedText: value.committedText,
+        confirmationDigest,
+    };
+}
+function parseGovernedHandoff(body) {
+    const value = body.governedHandoff;
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isRecord(value)) {
+        return badRequest("governedHandoff must be an object when provided.");
+    }
+    return value;
+}
+function parseVoiceOrigin(body, governedHandoff) {
+    const value = body.voiceOrigin;
+    if (value === undefined) {
+        return undefined;
+    }
+    if (governedHandoff === undefined) {
+        return badRequest("voiceOrigin requires governedHandoff.");
+    }
+    if (!isRecord(value)) {
+        return badRequest("voiceOrigin must be an object when provided.");
+    }
+    return parseVoiceOriginFields(value);
+}
 function resolveKind(body) {
     const workflowId = body.workflowId;
     const taskType = body.taskType;
@@ -176,18 +274,16 @@ function validateRunInput(kind, input) {
     }
     return validateBugInvestigationInput(input);
 }
-// Parses the raw JSON text into a validated RunRequest, or a typed BAD_REQUEST error.
-export function parseRunRequest(raw) {
-    let parsed;
+function parseJsonObject(raw) {
     try {
-        parsed = JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        return isRecord(parsed) ? parsed : badRequest("Request body must be a JSON object.");
     }
     catch {
-        return { code: "BAD_REQUEST", message: "Request body is not valid JSON." };
-    }
-    if (!isRecord(parsed)) {
-        return { code: "BAD_REQUEST", message: "Request body must be a JSON object." };
+        return badRequest("Request body is not valid JSON.");
     }
+}
+function parseRunRequestCore(parsed) {
     const kind = resolveKind(parsed);
     if (typeof kind !== "string") {
         return kind;
@@ -208,12 +304,64 @@ export function parseRunRequest(raw) {
     return {
         kind,
         modelId,
+        input,
+        limits: isRecord(limits) ? limits : undefined,
+    };
+}
+function parseGovernedHandoffMetadata(parsed) {
+    if (parsed.governedHandoffVoiceAction !== undefined) {
+        return badRequest("governedHandoffVoiceAction is server-generated and must not be provided.");
+    }
+    const governedHandoff = parseGovernedHandoff(parsed);
+    if (isRunRequestError(governedHandoff)) {
+        return governedHandoff;
+    }
+    const governedHandoffSourceGroundedRunId = parseOptionalString(parsed, "governedHandoffSourceGroundedRunId");
+    if (isRunRequestError(governedHandoffSourceGroundedRunId)) {
+        return governedHandoffSourceGroundedRunId;
+    }
+    if (governedHandoffSourceGroundedRunId !== undefined && governedHandoff === undefined) {
+        return badRequest("governedHandoffSourceGroundedRunId requires governedHandoff.");
+    }
+    const governedHandoffVoiceOrigin = parseVoiceOrigin(parsed, governedHandoff);
+    if (isRunRequestError(governedHandoffVoiceOrigin)) {
+        return governedHandoffVoiceOrigin;
+    }
+    return { governedHandoff, governedHandoffSourceGroundedRunId, governedHandoffVoiceOrigin };
+}
+function buildRunRequest(core, metadata) {
+    return {
+        kind: core.kind,
+        modelId: core.modelId,
         // Dry-run-first (ADR-0011 D8 / security M1): the create route NEVER applies, even if the client
         // body carries `apply:true`. Applying is the sole responsibility of POST /api/runs/:runId/apply
         // (route 9), which re-invokes the workflow through the gated path. A one-shot create-with-apply
         // would bypass the explicit review→apply step, so the body flag is deliberately ignored here.
         apply: false,
-        input,
-        ...(isRecord(limits) ? { limits } : { limits: undefined }),
+        input: core.input,
+        limits: core.limits,
+        ...(metadata.governedHandoff === undefined ? {} : { governedHandoff: metadata.governedHandoff }),
+        ...(metadata.governedHandoffSourceGroundedRunId === undefined
+            ? {}
+            : { governedHandoffSourceGroundedRunId: metadata.governedHandoffSourceGroundedRunId }),
+        ...(metadata.governedHandoffVoiceOrigin === undefined
+            ? {}
+            : { governedHandoffVoiceOrigin: metadata.governedHandoffVoiceOrigin }),
     };
 }
+// Parses the raw JSON text into a validated RunRequest, or a typed BAD_REQUEST error.
+export function parseRunRequest(raw) {
+    const parsed = parseJsonObject(raw);
+    if (isRunRequestError(parsed)) {
+        return parsed;
+    }
+    const core = parseRunRequestCore(parsed);
+    if (isRunRequestError(core)) {
+        return core;
+    }
+    const metadata = parseGovernedHandoffMetadata(parsed);
+    if (isRunRequestError(metadata)) {
+        return metadata;
+    }
+    return buildRunRequest(core, metadata);
+}

package/dist/runtime/capabilityDetector.d.ts

@@ -0,0 +1,38 @@
+import { type RuntimeCapabilitiesResponse, type RuntimeCapabilityKind, type RuntimeCapabilityState, type RuntimeCapabilityUnavailableReason } from "@oscharko-dev/keiko-contracts";
+import { type WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import type { WorkspaceFs } from "@oscharko-dev/keiko-workspace";
+export declare const DEFAULT_RUNTIME_CAPABILITY_DEADLINE_MS: 250;
+export interface HostExecutableSpec {
+    readonly id: string;
+    readonly kind: Exclude<RuntimeCapabilityKind, "command-source">;
+    readonly executable: string;
+    readonly label: string;
+    readonly remediationHint: string;
+}
+export interface HostExecutableProbeResult {
+    readonly state: RuntimeCapabilityState;
+    readonly unavailableReason?: RuntimeCapabilityUnavailableReason | undefined;
+    readonly version?: string | undefined;
+}
+export interface HostExecutableProbe {
+    probe(executable: string, workspaceRoot: string | undefined): HostExecutableProbeResult;
+}
+export interface RuntimeCapabilityDetectorOptions {
+    readonly workspace?: WorkspaceInfo | undefined;
+    readonly fs?: WorkspaceFs | undefined;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    readonly platform?: NodeJS.Platform | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly deadlineMs?: number | undefined;
+    readonly probe?: HostExecutableProbe | undefined;
+    readonly specs?: readonly HostExecutableSpec[] | undefined;
+}
+export declare const RUNTIME_HOST_EXECUTABLE_SPECS: readonly HostExecutableSpec[];
+export declare class PathHostExecutableProbe implements HostExecutableProbe {
+    private readonly env;
+    private readonly platform;
+    constructor(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform);
+    probe(executable: string, workspaceRoot: string | undefined): HostExecutableProbeResult;
+}
+export declare function detectRuntimeCapabilities(options?: RuntimeCapabilityDetectorOptions): RuntimeCapabilitiesResponse;
+//# sourceMappingURL=capabilityDetector.d.ts.map

package/dist/runtime/capabilityDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilityDetector.d.ts","sourceRoot":"","sources":["../../src/runtime/capabilityDetector.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,2BAA2B,EAEhC,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,kCAAkC,EAGxC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAGtF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,eAAO,MAAM,sCAAsC,EAAG,GAAY,CAAC;AAKnE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,qBAAqB,EAAE,gBAAgB,CAAC,CAAC;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,kCAAkC,GAAG,SAAS,CAAC;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,yBAAyB,CAAC;CACzF;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,CAAC;CAC5D;AAED,eAAO,MAAM,6BAA6B,EAAE,SAAS,kBAAkB,EA4FrE,CAAC;AA6GH,qBAAa,uBAAwB,YAAW,mBAAmB;IACjE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;gBAGzC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,QAAQ,GAAE,MAAM,CAAC,QAA2B;IAMvC,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,yBAAyB;CAqB/F;AAwRD,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,gCAAqC,GAC7C,2BAA2B,CAsB7B"}