@openpond/harness 0.2.6 → 0.4.0

package/CONTRACT.md

@@ -51,3 +51,78 @@ unselected evidence remains available to a later host watermark.
 Evaluation execution and model-improvement qualification contracts that bind a
 Harness to a Taskset, scored baseline, Model, verifier, and training signal
 belong to `@openpond/evals`.
+
+## Released source transport
+
+### Profile workflow catalog
+
+A Git-backed Profile may contain `workflows/catalog.json` beside its Skills,
+Agents, and evals. The file uses `openpond.profileWorkflows.v1`:
+
+```json
+{
+  "schemaVersion": "openpond.profileWorkflows.v1",
+  "workflows": [{
+    "id": "weekly-report",
+    "label": "Weekly report",
+    "description": "Summarize a supplied week.",
+    "inputSchema": { "type": "object", "properties": { "week": { "type": "integer" } }, "required": ["week"] },
+    "invocation": { "kind": "instructions", "instructions": "Write the report for the supplied week." },
+    "skillPaths": ["skills/report/SKILL.md"]
+  }]
+}
+```
+
+Workflow IDs are stable within one catalog. `skillPaths` name enabled primary
+Skill files in the released Harness source. An `agent_action` invocation names
+an enabled Agent action from the Profile action catalog. Import retains its
+identity, input schema, and Agent source in the same immutable release; the
+host executes it through the existing Agent SDK runner. Duplicate IDs, unsafe
+paths, missing references, invalid input schemas, and unsupported actions fail
+import. The catalog's exact bytes and generated `workflows/actions.json`
+inventory are included in the Harness release. Profile eval files remain
+outside model-visible Harness content.
+
+`openpond.profileWorkflowBinding.v1` names the Profile, accepted source
+revision, Harness release, catalog content hash, and workflow ID. The host
+resolves it from a fully verified source package. A bound Work session uses
+that release for every turn; source updates create new releases for fresh
+sessions and do not change admitted runs or personal Harness selection.
+
+Local servers expose committed workflow bindings at `GET /v1/profile/workflows`.
+Create a Work session with its `currentProfile` and returned
+`profileWorkflowBinding`, then start a turn with `workflowInput` matching the
+workflow's `inputSchema`. The turn records its binding and input hash.
+
+`openpond.harnessSourcePackage.v1` carries the complete immutable Agent
+snapshot, Harness release and their released file bytes. Creation and readback
+verify both release hashes, dependency references, the exact file population,
+canonical base64, individual file hashes and a 25 MiB total byte limit.
+Rehashing a transport envelope does not authorize different source bytes.
+Instruction and Skill entry files must be policy-visible; verifier and
+host-private assets retain their declared visibility and must never be exposed
+to a policy by iterating the complete source map.
+
+This is source transport, not runtime conformance. Hosts authorize export and
+select an execution adapter that consumes the captured source, verifies its
+capabilities and records effective context. A matching Harness release hash
+alone does not prove that instructions, Skills or executable dependencies ran.
+
+`createHarnessSourceRuntime` consumes captured source for the declarative
+`openpond.agent-runtime.v1` program. It loads released instruction and Skill
+text, verifies required capabilities, dependency versions and actual tool
+schemas, and exposes policy-visible resources through bounded byte-range reads.
+Private assets never enter its context or reader. Unsupported programs and
+released subagents fail admission. Hosts must provide their actual tools and
+capabilities; this helper does not implement missing execution capabilities.
+The runtime receipt binds the source, effective system prompt, loaded assets
+and tool definitions. Hosts retain that receipt with attempt evidence.
+
+`executeHarnessRollout` owns the shared policy/environment round lifecycle,
+released resource calls, retained conversation and exhaustion behavior. Hosts
+supply policy transport and environment step/termination operations. Desktop's
+agent runtime re-exports the same provider loop from this package.
+`@openpond/harness/runtime-source` distributes a self-contained ESM build of
+source admission and rollout execution with its SHA-256. Hosted archives use
+those published bytes instead of implementing a second source reader or loop.
+The clean consumer check executes this distribution without module resolution.

package/dist/index.js

@@ -10,3 +10,8 @@ export * from "./refiner-detection.js";
 export * from "./refinement-lifecycle.js";
 export * from "./refiner-support.js";
 export * from "./tools.js";
+export * from "./source-package.js";
+export * from "./source-runtime.js";
+export * from "./provider-loop.js";
+export * from "./profile-workflows.js";
+export * from "./source-execution.js";

package/dist/profile-workflows.js

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { contentHash, ImmutableReleaseRefSchema, ReleaseHashSchema, sha256 } from "./common.js";
+import { harnessSourcePackageFiles, validateHarnessSourcePackage } from "./source-package.js";
+const WorkflowIdSchema = z.string().regex(/^[a-z][a-z0-9_-]{0,119}$/);
+const SourcePathSchema = z.string().min(1).max(2_000).refine((value) => !value.includes("\\") && !value.includes(":") && !value.startsWith("/")
+    && value.split("/").every((part) => part !== "" && part !== "." && part !== ".."), "workflow references require portable relative paths");
+export const ProfileWorkflowSchema = z.object({
+    id: WorkflowIdSchema,
+    label: z.string().trim().min(1).max(240),
+    description: z.string().max(4_000),
+    inputSchema: z.record(z.string(), z.unknown()),
+    invocation: z.discriminatedUnion("kind", [
+        z.object({ kind: z.literal("instructions"), instructions: z.string().trim().min(1).max(100_000) }).strict(),
+        z.object({ kind: z.literal("agent_action"), actionId: z.string().trim().min(1).max(240) }).strict(),
+    ]),
+    skillPaths: z.array(SourcePathSchema).max(100),
+}).strict();
+export const ProfileWorkflowCatalogSchema = z.object({
+    schemaVersion: z.literal("openpond.profileWorkflows.v1"),
+    workflows: z.array(ProfileWorkflowSchema).max(1_000),
+}).strict();
+/** Action identities retained beside a released workflow catalog. The host
+ * resolves these identities to the Agent files in the same immutable release. */
+export const ProfileWorkflowActionSchema = z.object({
+    id: z.string().trim().min(1).max(240),
+    agentId: z.string().regex(/^[a-zA-Z0-9_-]{1,240}$/),
+    sourceActionId: z.string().trim().min(1).max(240),
+    inputSchema: z.record(z.string(), z.unknown()),
+}).strict();
+export const ProfileWorkflowActionsSchema = z.object({
+    schemaVersion: z.literal("openpond.profileWorkflowActions.v1"),
+    actions: z.array(ProfileWorkflowActionSchema).max(200),
+}).strict();
+/** Validates references against the exact files admitted to a released source. */
+export function validateProfileWorkflowCatalog(input) {
+    const catalog = ProfileWorkflowCatalogSchema.parse(input.catalog);
+    const ids = new Set();
+    for (const workflow of catalog.workflows) {
+        if (ids.has(workflow.id))
+            throw new Error(`Duplicate Profile workflow id ${workflow.id}.`);
+        ids.add(workflow.id);
+        for (const skillPath of workflow.skillPaths) {
+            if (!input.sourcePaths.has(skillPath))
+                throw new Error(`Profile workflow ${workflow.id} references missing Skill ${skillPath}.`);
+        }
+        if (workflow.invocation.kind === "agent_action" && !input.actionIds.has(workflow.invocation.actionId)) {
+            throw new Error(`Profile workflow ${workflow.id} references missing action ${workflow.invocation.actionId}.`);
+        }
+    }
+    return catalog;
+}
+export const ProfileWorkflowBindingSchema = z.object({
+    schemaVersion: z.literal("openpond.profileWorkflowBinding.v1"),
+    profileId: z.string().trim().min(1).max(240),
+    sourceRevision: z.string().trim().min(1).max(240),
+    harnessRelease: ImmutableReleaseRefSchema,
+    catalogHash: ReleaseHashSchema,
+    workflowId: WorkflowIdSchema,
+}).strict();
+/** Resolve a catalog only from a verified immutable source package. */
+export function loadReleasedProfileWorkflowCatalog(value) {
+    const sourcePackage = validateHarnessSourcePackage(value);
+    const files = harnessSourcePackageFiles(sourcePackage);
+    const loaded = loadReleasedProfileWorkflowCatalogAssets({
+        agentSnapshot: sourcePackage.agentSnapshot,
+        harnessRelease: sourcePackage.harnessRelease,
+        catalogBytes: files.get("workflows/catalog.json"),
+        actionBytes: files.get("workflows/actions.json"),
+    });
+    return { sourcePackage, ...loaded };
+}
+/** Load only the two workflow assets after the caller has verified all files
+ * in a local release. This avoids packaging large Agent source each turn. */
+export function loadReleasedProfileWorkflowCatalogAssets(input) {
+    const asset = input.harnessRelease.files.find((file) => file.path === "workflows/catalog.json");
+    const actionAsset = input.harnessRelease.files.find((file) => file.path === "workflows/actions.json");
+    if (!asset || asset.visibility !== "policy" || !input.catalogBytes || sha256(input.catalogBytes) !== asset.contentHash) {
+        throw new Error("Released Profile workflow catalog is unavailable or invalid.");
+    }
+    if (!actionAsset || actionAsset.visibility !== "policy" || !input.actionBytes || sha256(input.actionBytes) !== actionAsset.contentHash) {
+        throw new Error("Released Profile workflow actions are unavailable or invalid.");
+    }
+    const actions = ProfileWorkflowActionsSchema.parse(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.actionBytes))).actions;
+    const actionIds = new Set();
+    for (const action of actions) {
+        if (actionIds.has(action.id))
+            throw new Error(`Duplicate released Profile action ${action.id}.`);
+        actionIds.add(action.id);
+        if (!input.harnessRelease.files.some((file) => file.path.startsWith(`agents/${action.agentId}/`))) {
+            throw new Error(`Released Profile action ${action.id} lacks its Agent source.`);
+        }
+    }
+    const catalog = validateProfileWorkflowCatalog({
+        catalog: JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.catalogBytes)),
+        sourcePaths: new Set(input.agentSnapshot.skills.map((skill) => skill.path)),
+        actionIds,
+    });
+    return { catalog, catalogHash: contentHash(catalog), actions };
+}
+export function resolveReleasedProfileWorkflowCatalogBinding(input) {
+    const binding = ProfileWorkflowBindingSchema.parse(input.binding);
+    if (binding.harnessRelease.id !== input.harnessRelease.id
+        || binding.harnessRelease.contentHash !== input.harnessRelease.contentHash) {
+        throw new Error("Profile workflow binding differs from the released source package.");
+    }
+    if (binding.catalogHash !== input.catalogHash)
+        throw new Error("Profile workflow catalog differs from its binding.");
+    const profile = input.harnessRelease.metadata.profile;
+    if (!profile || typeof profile !== "object")
+        throw new Error("Released source lacks Profile provenance.");
+    const provenance = profile;
+    if (provenance.id !== binding.profileId || provenance.sourceRevision !== binding.sourceRevision) {
+        throw new Error("Profile workflow binding differs from released Profile provenance.");
+    }
+    const workflow = input.catalog.workflows.find((candidate) => candidate.id === binding.workflowId);
+    if (!workflow)
+        throw new Error(`Profile workflow ${binding.workflowId} is absent from its bound catalog.`);
+    return workflow;
+}
+export function resolveReleasedProfileWorkflow(input) {
+    const binding = ProfileWorkflowBindingSchema.parse(input.binding);
+    const { sourcePackage, catalog, catalogHash } = loadReleasedProfileWorkflowCatalog(input.sourcePackage);
+    return resolveReleasedProfileWorkflowCatalogBinding({ binding, harnessRelease: sourcePackage.harnessRelease, catalog, catalogHash });
+}
+export function resolveProfileWorkflowBinding(input) {
+    const binding = ProfileWorkflowBindingSchema.parse(input.binding);
+    if (binding.harnessRelease.id !== input.harnessRelease.id
+        || binding.harnessRelease.contentHash !== input.harnessRelease.contentHash) {
+        throw new Error("Profile workflow binding differs from the admitted Harness release.");
+    }
+    const catalog = validateProfileWorkflowCatalog(input);
+    if (contentHash(catalog) !== binding.catalogHash)
+        throw new Error("Profile workflow catalog differs from its binding.");
+    const workflow = catalog.workflows.find((candidate) => candidate.id === binding.workflowId);
+    if (!workflow)
+        throw new Error(`Profile workflow ${binding.workflowId} is absent from its bound catalog.`);
+    return workflow;
+}

package/dist/provider-loop.js

@@ -0,0 +1,70 @@
+export async function* providerRoundSequence(input) {
+    if (!Number.isInteger(input.maxRounds) || input.maxRounds < 1) {
+        throw new Error("Provider maxRounds must be a positive integer.");
+    }
+    for (let index = 0; index < input.maxRounds; index += 1) {
+        if (input.signal.aborted)
+            throw input.signal.reason ?? new Error("Provider loop interrupted.");
+        yield {
+            index,
+            requestId: `${input.turnId}:model:${index}`,
+            signal: input.signal
+        };
+    }
+}
+/** Owns provider/tool round sequencing, completion, exhaustion, and aborts. */
+export async function runProviderRoundLoop(input) {
+    for await (const round of providerRoundSequence(input)) {
+        const decision = await input.runRound(round);
+        if (decision.type === "complete")
+            return decision.result;
+    }
+    return input.onExhausted();
+}
+/**
+ * Owns provider stream consumption and the normalized round result. The host
+ * supplies the provider request, usage recorder, and provider-specific delta
+ * shapes without duplicating the stream lifecycle.
+ */
+export async function runProviderRound(input) {
+    let text = "";
+    let reasoningText = "";
+    let usage;
+    let continuation = null;
+    let finishReason;
+    const toolCallBatches = [];
+    try {
+        for await (const delta of input.stream) {
+            await input.onDelta?.(delta);
+            if (input.signal.aborted) {
+                throw input.signal.reason ?? new Error("Provider round interrupted.");
+            }
+            if (delta.text)
+                text += delta.text;
+            if (delta.reasoningText)
+                reasoningText += delta.reasoningText;
+            if (delta.usage !== undefined)
+                usage = delta.usage;
+            if (delta.continuation !== undefined)
+                continuation = delta.continuation;
+            if (delta.toolCalls)
+                toolCallBatches.push([...delta.toolCalls]);
+            if (delta.finishReason !== undefined)
+                finishReason = delta.finishReason;
+        }
+        const result = {
+            text,
+            reasoningText,
+            usage,
+            continuation,
+            toolCallBatches,
+            finishReason,
+        };
+        await input.onCompleted?.(result);
+        return result;
+    }
+    catch (error) {
+        await input.onFailed?.(error);
+        throw error;
+    }
+}