@sgtbeatdown/wolfpack-tasks 0.0.0-stage → 0.2.0

package/src/configured-task-core.ts

@@ -0,0 +1,76 @@
+import type { TaskCore, WakeRequest } from "./task-core";
+import { TaskProtocolError } from "./task-protocol";
+import { createTaskStore } from "./task-store";
+import { createVolatileTaskSession } from "./volatile-task-session";
+import { wolfpackLocalHeaders } from "./wolfpack-local-auth";
+
+export interface OwnedTaskCore extends TaskCore {
+  /** Fence new work, abort requests, settle active calls, then discard RAM state. */
+  close(): Promise<void>;
+}
+export interface ConfiguredTaskCoreOptions {
+  readonly sessionName?: string;
+  readonly baseUrl?: string;
+  readonly fetch?: typeof fetch;
+  readonly requestTimeoutMs?: number;
+  /** Fresh-lifetime registration after accepted state loss; the extension uses it only for structured relay-loss evidence. */
+  readonly rebind?: boolean;
+}
+
+/** Normal extension transport. Never probe/fallback to the legacy durable relay. */
+export async function createConfiguredTaskCore(options: ConfiguredTaskCoreOptions = {}, signal?: AbortSignal): Promise<OwnedTaskCore> {
+  const sessionName = options.sessionName ?? process.env.WOLFPACK_SESSION_NAME;
+  if (!sessionName?.trim()) throw new TaskProtocolError("RELAY_UNAVAILABLE", "WOLFPACK_SESSION_NAME is required for the Wolfpack task adapter");
+  const port = process.env.WOLFPACK_PORT ?? "18790";
+  if (options.baseUrl === undefined && (!/^[0-9]+$/.test(port) || Number(port) < 1 || Number(port) > 65535)) throw new TypeError("invalid WOLFPACK_PORT");
+  const base = new URL(options.baseUrl ?? `http://127.0.0.1:${port}`);
+  if (base.username || base.password || base.search || base.hash || base.pathname !== "/") throw new TypeError("relay base URL must be an origin");
+  const url = new URL("/api/task-relay/volatile-v1", base).href;
+  const store = createTaskStore();
+  let session: ReturnType<typeof createVolatileTaskSession> | undefined;
+  try {
+    const requestFetch = options.fetch ?? fetch;
+    const authenticated = Object.assign((input: Parameters<typeof fetch>[0], init?: RequestInit) => requestFetch(input, { ...init, headers: wolfpackLocalHeaders(url, init?.headers) }), { preconnect: requestFetch.preconnect }) as typeof fetch;
+    session = createVolatileTaskSession({ url, callerSession: sessionName, store, fetch: authenticated, ...(options.requestTimeoutMs !== undefined && { requestTimeoutMs: options.requestTimeoutMs }) });
+    const core = await (options.rebind ? session.rebind(signal) : session.connect(signal));
+    const active = new Set<Promise<unknown>>();
+    let closed = false, closing: Promise<void> | undefined;
+    const owned = { ...core } as OwnedTaskCore;
+    const track = <T>(result: Promise<T>): Promise<T> => {
+      active.add(result);
+      void result.then(() => active.delete(result), () => active.delete(result));
+      return result;
+    };
+    for (const [key, value] of Object.entries(core)) {
+      if (typeof value !== "function") continue;
+      Object.defineProperty(owned, key, { enumerable: true, value: (...args: unknown[]) => {
+        if (closed) throw new TaskProtocolError("RELAY_CLOSED", "task session is closed", { retryable: false });
+        // Core methods may call sibling methods through `this` (notably intent ACK).
+        // Keep their original receiver while the outer promise owns the full operation.
+        const result: unknown = value.apply(core, args);
+        if (key === "recordWakeRequest") {
+          const request = result as WakeRequest;
+          return {
+            flush: (signal?: AbortSignal): Promise<void> => {
+              if (closed) throw new TaskProtocolError("RELAY_CLOSED", "task session is closed", { retryable: false });
+              return track(request.flush(signal));
+            },
+            // A closed session drops its store; there is nothing left to withdraw.
+            discard: () => { if (!closed) request.discard(); },
+          };
+        }
+        return result instanceof Promise ? track(result) : result;
+      } });
+    }
+    owned.close = () => {
+      if (closing) return closing;
+      closed = true;
+      session!.close();
+      closing = Promise.allSettled([...active]).then(() => { store.close(); });
+      return closing;
+    };
+    return owned;
+  } catch (error) {
+    session?.close(); store.close(); throw error;
+  }
+}

package/src/extension.ts

@@ -0,0 +1,51 @@
+import type { AgentToolResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import { createAgentTaskRuntime, defaultCoreFactory } from "./agent-task-runtime";
+import type { AgentTaskToolResult, ConfiguredCoreFactory } from "./agent-task-runtime";
+import type { TaskCore } from "./task-core";
+
+export {
+	ACTIVE_POLL_MS,
+	IDLE_POLL_MS,
+	WORKER_COORDINATION_FORBIDDEN_CODE,
+	WORKER_GATE_DENIAL_CODE,
+	createConfiguredCoreLoader,
+	createSingleFlightInboxRefresh,
+	outboxFailureStatus,
+} from "./agent-task-runtime";
+export type { ConfiguredCoreFactory, ConfiguredCoreLoader } from "./agent-task-runtime";
+
+/** Registers endpoint-owned tools using the memory-owned Wolfpack transport by default. */
+export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefined = undefined, createCore: ConfiguredCoreFactory = defaultCoreFactory): void {
+	// Delegate at call time: hosts and tests may replace these methods after registration.
+	const { lifecycle, tools } = createAgentTaskRuntime({
+		sendMessage(message, options) { pi.sendMessage(message, options); },
+		appendEntry(customType, data) { pi.appendEntry(customType, data); },
+	}, core, createCore);
+	pi.on("tool_call", lifecycle.tool_call);
+	pi.on("session_start", lifecycle.session_start);
+	pi.on("agent_end", lifecycle.agent_end);
+	pi.on("agent_settled", lifecycle.agent_settled);
+	pi.on("turn_end", lifecycle.turn_end);
+	pi.on("session_shutdown", lifecycle.session_shutdown);
+	for (const tool of tools) {
+		pi.registerTool({
+			name: tool.name,
+			label: tool.label,
+			description: tool.description,
+			parameters: tool.parameters,
+			execute: (toolCallId, params, signal, onUpdate, context): Promise<AgentToolResult<unknown>> => tool.execute(toolCallId, params, signal, onUpdate, context),
+			renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+		});
+	}
+}
+
+export default function piTasks(pi: ExtensionAPI): void {
+	registerAgentTaskTools(pi);
+}
+
+function text(result: Pick<AgentTaskToolResult, "content"> | { readonly content?: readonly unknown[] }): string {
+	const first = result.content?.[0];
+	return first && typeof first === "object" && "type" in first && first.type === "text" && "text" in first && typeof first.text === "string" ? first.text : "";
+}

package/src/in-memory-task-relay.ts

@@ -0,0 +1,115 @@
+import {
+	MAX_RELAY_PAYLOAD_BYTES,
+	TASK_PROTOCOL_VERSION,
+	TaskProtocolError,
+} from "./task-protocol";
+import type {
+	RelayAcceptance,
+	RelayConnectInput,
+	RelayConnection,
+	RelayDeliveryAck,
+	RelayEnvelope,
+	RelayInboxPage,
+	RelayReceiveRequest,
+	RelayTargetReference,
+	TaskEndpoint,
+	TaskRelay,
+} from "./task-protocol";
+
+interface MailboxItem {
+	readonly cursor: string;
+	readonly envelope: RelayEnvelope;
+}
+
+/** Deterministic conformance fixture; production relays must provide durable storage. */
+export function createInMemoryTaskRelay(id: string): InMemoryTaskRelay {
+	return new InMemoryTaskRelay(id);
+}
+
+export class InMemoryTaskRelay implements TaskRelay {
+	readonly id: string;
+	private readonly endpoints = new Map<string, TaskEndpoint>();
+	private readonly mailboxes = new Map<string, MailboxItem[]>();
+	private readonly accepted = new Set<string>();
+	private readonly acknowledged = new Set<string>();
+	private nextDelivery = 0;
+	private sendFailure = false;
+
+	constructor(id: string) {
+		this.id = id;
+	}
+
+	async connect(input: RelayConnectInput): Promise<RelayConnection> {
+		if (input.protocolVersion !== TASK_PROTOCOL_VERSION) throw new TaskProtocolError("INCOMPATIBLE_PROTOCOL", "task endpoint protocol is incompatible");
+		this.assertEndpoint(input.endpoint);
+		this.endpoints.set(input.endpoint.id, input.endpoint);
+		if (!this.mailboxes.has(input.endpoint.id)) this.mailboxes.set(input.endpoint.id, []);
+		return { endpoint: input.endpoint, receiveCursor: input.receiveCursor };
+	}
+
+	async resolve(input: RelayTargetReference): Promise<TaskEndpoint> {
+		if (input.relay !== this.id) throw new TaskProtocolError("UNKNOWN_RELAY", "target belongs to another relay");
+		const endpoint = this.endpoints.get(input.reference);
+		if (!endpoint) throw new TaskProtocolError("UNREGISTERED_TARGET", "target is not registered for this protocol");
+		return endpoint;
+	}
+
+	async send(input: RelayEnvelope): Promise<RelayAcceptance> {
+		if (this.sendFailure) {
+			this.sendFailure = false;
+			throw new Error("in-memory relay send failed");
+		}
+		this.assertEnvelope(input);
+		if (this.accepted.has(input.envelopeId)) return { envelopeId: input.envelopeId };
+		const mailbox = this.mailboxes.get(input.target.id);
+		if (!mailbox) throw new TaskProtocolError("UNREGISTERED_TARGET", "target is not registered for this protocol");
+		this.accepted.add(input.envelopeId);
+		mailbox.push({ cursor: String(++this.nextDelivery), envelope: input });
+		return { envelopeId: input.envelopeId };
+	}
+
+	async receive(input: RelayReceiveRequest): Promise<RelayInboxPage> {
+		this.assertEndpoint(input.endpoint);
+		const mailbox = this.mailboxes.get(input.endpoint.id);
+		if (!mailbox) throw new TaskProtocolError("UNREGISTERED_TARGET", "endpoint is not registered for this protocol");
+		const cursor = Number(input.cursor);
+		if (!Number.isSafeInteger(cursor) || cursor < 0) throw new TaskProtocolError("INVALID_CURSOR", "relay cursor must be a non-negative integer");
+		const start = cursor;
+		const pending = mailbox.filter((item) => Number(item.cursor) > start && !this.acknowledged.has(item.envelope.envelopeId));
+		const deliveries = pending.slice(0, input.limit);
+		return {
+			deliveries,
+			nextCursor: deliveries.at(-1)?.cursor ?? String(start),
+			hasMore: pending.length > deliveries.length,
+		};
+	}
+
+	async acknowledgeDelivery(input: RelayDeliveryAck): Promise<void> {
+		this.assertEndpoint(input.endpoint);
+		const cursor = Number(input.cursor);
+		if (!Number.isSafeInteger(cursor) || cursor < 0) throw new TaskProtocolError("INVALID_CURSOR", "relay cursor must be a non-negative integer");
+		const item = this.mailboxes.get(input.endpoint.id)?.find(item => item.cursor === input.cursor);
+		if (!item) throw new TaskProtocolError("INVALID_CURSOR", "relay delivery is not in this endpoint mailbox");
+		this.acknowledged.add(item.envelope.envelopeId);
+	}
+
+	failNextSend(): void {
+		this.sendFailure = true;
+	}
+
+	envelopesFor(endpoint: TaskEndpoint): readonly RelayEnvelope[] {
+		return (this.mailboxes.get(endpoint.id) ?? []).map((item) => item.envelope);
+	}
+
+	private assertEndpoint(endpoint: TaskEndpoint): void {
+		if (endpoint.relay !== this.id || endpoint.id.length === 0) throw new TaskProtocolError("INVALID_ENDPOINT", "endpoint must belong to this relay and have an opaque id");
+	}
+
+	private assertEnvelope(envelope: RelayEnvelope): void {
+		if (envelope.protocolVersion !== TASK_PROTOCOL_VERSION) throw new TaskProtocolError("INCOMPATIBLE_PROTOCOL", "envelope protocol is incompatible");
+		this.assertEndpoint(envelope.source);
+		this.assertEndpoint(envelope.target);
+		if (!this.endpoints.has(envelope.source.id)) throw new TaskProtocolError("UNREGISTERED_SOURCE", "source is not registered for this protocol");
+		if (new TextEncoder().encode(envelope.payload).byteLength > MAX_RELAY_PAYLOAD_BYTES) throw new TaskProtocolError("PAYLOAD_TOO_LARGE", "relay payload exceeds the protocol limit");
+	}
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export { createInMemoryTaskRelay, InMemoryTaskRelay } from "./in-memory-task-relay";
+export { createTaskCore } from "./task-core";
+export { createConfiguredTaskCore } from "./configured-task-core";
+export type { ConfiguredTaskCoreOptions, OwnedTaskCore } from "./configured-task-core";
+export { createTaskStore } from "./task-store";
+export { createVolatileTaskSession, VOLATILE_PROFILE } from "./volatile-task-session";
+export type { VolatileTaskSession, VolatileTaskSessionOptions } from "./volatile-task-session";
+export { WOLFPACK_TASK_RELAY_ID } from "./wolfpack-endpoint-view";
+export { runTaskRelayConformance } from "./task-relay-conformance";
+export {
+	MAX_RELAY_PAYLOAD_BYTES,
+	TASK_PROTOCOL_VERSION,
+	TaskEnvelopeKind,
+	TaskProtocolError,
+} from "./task-protocol";
+export type {
+	RelayAcceptance,
+	RelayConnectInput,
+	RelayConnection,
+	RelayDelivery,
+	RelayDeliveryAck,
+	RelayEnvelope,
+	RelayInboxPage,
+	RelayReceiveRequest,
+	RelayTargetReference,
+	RelayTransportBinding,
+	TaskEndpoint,
+	TaskEvent,
+	TaskIntent,
+	TaskRecord,
+	TaskRelay,
+} from "./task-protocol";
+export type { SubmitIntentOutcome, TaskCore, TaskCoreOptions, TaskInboxItem } from "./task-core";
+export type { PendingPresentation, PresentationRecord, TaskStore, TaskStoreOptions } from "./task-store";
+export type { TaskTimers } from "./task-work-scope";