@xopcai/xopc 0.0.251 → 0.0.253

package/dist/src/gateway/service.js

@@ -12,16 +12,16 @@ import { getSessionConfig } from "../storage/sqlite/config-repository.js";
 import "../storage/sqlite/index.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { init_agent_scope, listAgentEntries, normalizeAgentId, resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agent/agent-scope.js";
+import { buildSessionKey, init_session_key, sanitizeSegment } from "../routing/session-key.js";
+import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
+import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { init_paths, resolveConfigPath, resolveExtensionsDir } from "../config/paths.js";
-import { prewarmModelRegistry } from "../providers/model-registry.js";
 import { areExtensionsGloballyDisabled } from "../extensions/discover-extensions.js";
 import { buildExtensionMetadataSnapshot } from "../extensions/extension-metadata-snapshot.js";
 import { buildChannelCatalogForConfig, buildChannelCatalogFromSnapshot, init_channel_catalog_service } from "../channels/catalog/channel-catalog-service.js";
 import { loadConfig, saveConfig } from "../config/loader.js";
-import { buildSessionKey, init_session_key, sanitizeSegment } from "../routing/session-key.js";
-import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
+import { prewarmModelRegistry } from "../providers/model-registry.js";
 import { init_providers, providers_exports } from "../providers/index.js";
-import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { TaskRepository } from "../tasks/task-repository.js";
 import { TaskConversationRepository } from "../tasks/task-conversation-repository.js";
 import { getEmbeddedExecutionSession } from "../agent/embedded/execution-context.js";
@@ -50,7 +50,7 @@ import "../infra/bus/index.js";
 import { AgentService } from "../agent/service.js";
 import { ensureStarterAgentsInitialized } from "../agent/starter-agents.js";
 import { setPairingBroadcastSink } from "../channels/pairing/pairing-events.js";
-import { registerClarifyBridge } from "./clarify-runtime.js";
+import { registerClarificationChannelRuntime } from "./clarify-runtime.js";
 import { ChannelManager } from "../channels/manager.js";
 import { getWorkspacePath } from "../config/workspace-path-helpers.js";
 import "../config/index.js";
@@ -97,12 +97,13 @@ import { assertGatewayRuntimeConfig } from "./runtime-config.js";
 import { auditGatewayConfig } from "./security/audit.js";
 import { getXopcCloudCatalogCoordinator } from "../providers/xopc-cloud-catalog-coordinator.js";
 import { ModelCatalogSyncService } from "../providers/model-catalog-sync-service.js";
+import { collectMediaUrisFromMessages, deleteMediaUris } from "../media/session-references.js";
 import { runBootstrapMigrationsSync } from "../migrations/runner.js";
 import { NotificationService } from "../notifications/service.js";
 import { LocalAppService } from "../local-apps/service.js";
 import "../local-apps/index.js";
-import { createRuntimeBrowserRecipeService } from "../browser/recipes/runtime-service.js";
-import "../browser/recipes/index.js";
+import { createRuntimeBrowserAutomationService } from "../browser/automations/runtime-service.js";
+import "../browser/automations/index.js";
 import { mapProductEventToProactive } from "../proactive/events/product-event-bridge.js";
 import { ProactiveEventService } from "../proactive/service.js";
 import { ReadonlyProactiveAgentExecutor } from "../proactive/execution/agent-executor.js";
@@ -145,7 +146,7 @@ var GatewayService = class {
 	_agentService = null;
 	channelManager;
 	automationService;
-	browserRecipeService = null;
+	browserAutomationService = null;
 	notesService;
 	extensionLoader = null;
 	extensionMetadataSnapshot = null;
@@ -237,12 +238,12 @@ var GatewayService = class {
 	getModelCatalogSync() {
 		return this.modelCatalogSync;
 	}
-	get browserRecipes() {
-		if (!this.browserRecipeService) this.browserRecipeService = createRuntimeBrowserRecipeService({
+	get browserAutomations() {
+		if (!this.browserAutomationService) this.browserAutomationService = createRuntimeBrowserAutomationService({
 			getConfig: () => this.config,
 			emit: (type, payload) => this.emit(type, payload)
 		});
-		return this.browserRecipeService;
+		return this.browserAutomationService;
 	}
 	stopGatewayUpdateCheck = null;
 	/** When set (e.g. by `GatewayServer`), `triggerGatewayProcessRestart` can stop HTTP then exit. */
@@ -268,7 +269,7 @@ var GatewayService = class {
 	stopRealtimeLogBridge = null;
 	/**
 	* Webchat agent invocation surface (`runAgent`, `abortAgentRun`, `steer*`,
-	* `submitClarifyResponse`, clarify-bridge dispatch). Owns the
+	* clarification dispatch). Owns the
 	* `activeWebchatRunBySession` + `runAbortControllers` maps.
 	*/
 	agentRunner;
@@ -465,8 +466,12 @@ var GatewayService = class {
 			getParentMetadata: (sessionKey) => this.sessionIndex.getSessionMetadata(sessionKey),
 			loadParentMessages: (sessionKey) => this.sessionIndex.getStore().load(sessionKey),
 			getDefaultModelRef: (sessionKey) => this.ensureAgentService().getModelForSession(sessionKey),
+			getDefaultThinkingLevel: (sessionKey) => this.ensureAgentService().getThinkingLevelForSession(sessionKey),
 			getWorkspacePath: (metadata) => metadata.cwd || this.currentWorkspacePath,
-			onBeforeDispose: (sideChatId, clientInstanceId) => sideChatRuns?.cancelRun(sideChatId, clientInstanceId).then(() => void 0),
+			onBeforeDispose: async (sideChatId, clientInstanceId, messages) => {
+				await sideChatRuns?.cancelRun(sideChatId, clientInstanceId);
+				await deleteMediaUris(collectMediaUrisFromMessages(messages));
+			},
 			onExpired: (sideChatId, clientInstanceId, reason) => {
 				const topic = `side-chat:${clientInstanceId}:${sideChatId}`;
 				this.realtime.broker.publish(topic, "expired", { reason });
@@ -552,7 +557,8 @@ var GatewayService = class {
 			extensionRegistry: this.extensionLoader?.getRegistry(),
 			endpointTools: this.endpointTools,
 			getAutomationService: () => this.automationService,
-			getBrowserRecipeService: () => this.browserRecipes,
+			getBrowserAutomationService: () => this.browserAutomations,
+			emitBrowserEvent: (type, payload) => this.emit(type, payload),
 			getNotesService: () => this.notesService,
 			getProjectService: () => this.projects,
 			getLocalAppService: () => this.localApps,
@@ -571,10 +577,12 @@ var GatewayService = class {
 				}
 				return null;
 			},
-			gatewayClarify: { requestClarification: (sessionKey, request) => {
-				const executionSessionKey = getEmbeddedExecutionSession() ?? sessionKey;
+			gatewayClarify: { requestClarification: (context, request) => {
+				const executionSessionKey = getEmbeddedExecutionSession() ?? context.sessionKey;
 				return this.agentRunner.requestClarification({
 					sessionKey: executionSessionKey,
+					runId: context.runId,
+					toolCallId: context.toolCallId,
 					request,
 					publishStreamFor: (_runId) => (event) => {
 						this._agentService.turnDispatcher.enqueueWebchatStreamEvent(executionSessionKey, event);
@@ -592,7 +600,7 @@ var GatewayService = class {
 			getDefaultAgentId: () => getDefaultAgentId(this.config),
 			prepareAgentSession: (input) => prepareAutomationAgentSession(this.sessionIndex.getStore(), this.projects, input),
 			workflowRunService: this.createWorkflowRunService(),
-			browserRecipeService: this.browserRecipes,
+			browserAutomationService: this.browserAutomations,
 			executeTaskCommand: ({ taskId, idempotencyKey, command }) => {
 				const task = new TaskRepository().get(taskId);
 				if (!task) return {
@@ -775,8 +783,14 @@ var GatewayService = class {
 	getActiveWebchatRunId(sessionKey) {
 		return this.agentRunner.getActiveRunId(sessionKey);
 	}
-	submitClarifyResponse(requestId, answer) {
-		return this.agentRunner.submitClarifyResponse(requestId, answer);
+	answerEphemeralClarification(requestId, answer) {
+		return this.agentRunner.answerEphemeralClarification(requestId, answer);
+	}
+	getClarificationState(sessionKey) {
+		return this.agentRunner.getClarificationState(sessionKey);
+	}
+	resolveClarificationResponse(input) {
+		return this.agentRunner.resolveClarificationResponse(input);
 	}
 	initializeExtensionLoader() {
 		try {
@@ -924,7 +938,10 @@ var GatewayService = class {
 				errorMessage: readiness.error.message
 			}, `Initial XOPC Cloud catalog refresh failed: ${readiness.error.message}`);
 		}
-		registerClarifyBridge(this.agentRunner.getClarifyBridge());
+		registerClarificationChannelRuntime({
+			answerChoice: (requestId, choiceIndex, idempotencyKey) => this.agentRunner.answerClarificationChoice(requestId, choiceIndex, idempotencyKey),
+			answerText: (sessionKey, text, idempotencyKey) => this.agentRunner.answerClarificationText(sessionKey, text, idempotencyKey)
+		});
 		this.ensureAgentService();
 		this.agentRunner.recoverSessionInputs();
 		this.connectionRecovery.start();
@@ -1002,7 +1019,7 @@ var GatewayService = class {
 			getDefaultAgentId: () => getDefaultAgentId(this.config),
 			prepareAgentSession: (input) => prepareAutomationAgentSession(this.sessionIndex.getStore(), this.projects, input),
 			workflowRunService: this.createWorkflowRunService(),
-			browserRecipeService: this.browserRecipes,
+			browserAutomationService: this.browserAutomations,
 			executeTaskCommand: ({ taskId, idempotencyKey, command }) => {
 				const task = new TaskRepository().get(taskId);
 				if (!task) return {
@@ -1234,16 +1251,16 @@ var GatewayService = class {
 		this.connectedSourceChangePublisher = null;
 		this.connectedKnowledgeCoordinator?.stop();
 		this.connectedKnowledgeCoordinator = null;
-		await this.browserRecipeService?.shutdown();
+		await this.browserAutomationService?.shutdown();
 		if (this.browserExtensionRelease) {
 			await this.browserExtensionRelease();
 			this.browserExtensionRelease = null;
 		}
 		this.browserExtensionProvider = null;
 		this.browserExtensionBindKey = null;
-		registerClarifyBridge(null);
+		registerClarificationChannelRuntime(null);
 		this.connectionRecovery.stop();
-		this.agentRunner.disposeClarifyBridge();
+		this.agentRunner.disposeClarifications();
 		await disposeAllSessionMcpRuntimes().catch((err) => {
 			log.warn({ err }, "MCP runtime shutdown failed");
 		});
@@ -1263,33 +1280,29 @@ var GatewayService = class {
 		closeXopcDatabase();
 		log.debug("Gateway service stopped");
 	}
-	/** Start the browser extension WS server when backend is 'extension'. */
+	/** Start the browser extension WebSocket server when its driver is active. */
 	async startBrowserExtensionServerIfNeeded() {
 		await this.reconcileBrowserExtensionServer();
 	}
-	/** Release the gateway's hold on the shared extension bridge (does not restart). */
-	async releaseBrowserExtensionBridge() {
-		if (!this.browserExtensionRelease) return;
-		await this.browserExtensionRelease();
-		this.browserExtensionRelease = null;
-		this.browserExtensionProvider = null;
-		this.browserExtensionBindKey = null;
-		log.debug("Browser extension WS server released");
-	}
 	/**
 	* Start/stop/rebind the Chrome extension bridge.
 	* PATCH saves update config in memory without re-running gateway startup, so this must run on save too.
 	*/
 	async reconcileBrowserExtensionServer() {
-		const { resolveExtensionBridgeServerConfig } = await import("../browser/backend-from-config.js");
-		const bridgeConfig = resolveExtensionBridgeServerConfig(this.config);
+		const driver = this.config.browser.driver;
+		const bridgeConfig = this.config.browser.enabled && driver.kind === "extension" ? {
+			host: "127.0.0.1",
+			port: 19820,
+			connectionTimeout: this.config.browser.limits.actionTimeoutMs,
+			commandTimeout: this.config.browser.limits.actionTimeoutMs
+		} : null;
 		if (!bridgeConfig) {
 			if (this.browserExtensionRelease) {
 				await this.browserExtensionRelease();
 				this.browserExtensionRelease = null;
 				this.browserExtensionProvider = null;
 				this.browserExtensionBindKey = null;
-				log.debug("Browser extension WS server stopped (backend is not extension)");
+				log.debug("Browser extension WebSocket server stopped because its driver is inactive");
 			}
 			return;
 		}

package/dist/src/gateway/side-chat/manager.d.ts

@@ -11,13 +11,14 @@ export interface EphemeralSideChatManagerOptions {
     getParentMetadata: (sessionKey: string) => Promise<SessionMetadata | null>;
     loadParentMessages: (sessionKey: string) => Promise<AgentMessage[]>;
     getDefaultModelRef: (sessionKey: string) => string;
+    getDefaultThinkingLevel?: (sessionKey: string) => ThinkingLevel;
     getWorkspacePath: (metadata: SessionMetadata) => string;
     idleTtlMs?: number;
     maxPerClient?: number;
     maxTotal?: number;
     now?: () => number;
     startSweepTimer?: boolean;
-    onBeforeDispose?: (sideChatId: string, clientInstanceId: string) => void | Promise<void>;
+    onBeforeDispose?: (sideChatId: string, clientInstanceId: string, messages: AgentMessage[]) => void | Promise<void>;
     onExpired?: (sideChatId: string, clientInstanceId: string, reason: 'idle' | 'waiting') => void;
 }
 export declare class EphemeralSideChatManager {

package/dist/src/gateway/side-chat/manager.js

@@ -90,7 +90,7 @@ var EphemeralSideChatManager = class {
 		runtime.captureBaseline();
 		const config = {
 			modelRef: normalizeOptionalString(input.config?.modelRef) || this.options.getDefaultModelRef(parentSessionKey),
-			thinkingLevel: input.config?.thinkingLevel
+			thinkingLevel: input.config?.thinkingLevel ?? this.options.getDefaultThinkingLevel?.(parentSessionKey) ?? "medium"
 		};
 		const entry = {
 			id,
@@ -169,10 +169,11 @@ var EphemeralSideChatManager = class {
 		}
 		if (entry.clientInstanceId !== clientInstanceId) return false;
 		entry.status = "closing";
+		const messages = entry.runtime.loadConversationMessages();
 		this.entries.delete(id);
 		const cleanup = (async () => {
 			try {
-				await this.runBeforeDispose(id, clientInstanceId);
+				await this.runBeforeDispose(id, clientInstanceId, messages);
 				await evictEmbeddedSessionRunner(entry.runtime.runtimeId, "side_chat_dispose");
 				return true;
 			} finally {
@@ -255,9 +256,9 @@ var EphemeralSideChatManager = class {
 		entry.lastActiveAt = new Date(now).toISOString();
 		entry.expiresAt = entry.status === "running" ? null : new Date(now + this.idleTtlMs).toISOString();
 	}
-	async runBeforeDispose(id, clientInstanceId) {
+	async runBeforeDispose(id, clientInstanceId, messages) {
 		try {
-			await this.options.onBeforeDispose?.(id, clientInstanceId);
+			await this.options.onBeforeDispose?.(id, clientInstanceId, messages);
 		} catch (err) {
 			log.warn({
 				err,

package/dist/src/gateway/side-chat/run-service.d.ts

@@ -1,6 +1,7 @@
 import type { AgentService } from '../../agent/service.js';
 import type { GatewayAgentRunner } from '../service/agent-runner.js';
 import { type EphemeralSideChatManager } from './manager.js';
+import type { UserTurnAttachment } from '../user-turn-input.js';
 export interface SideChatRunServiceOptions {
     manager: EphemeralSideChatManager;
     getAgentService: () => AgentService;
@@ -12,7 +13,10 @@ export declare class SideChatRunService {
     private readonly options;
     private readonly activeBySideChat;
     constructor(options: SideChatRunServiceOptions);
-    submit(sideChatId: string, clientInstanceId: string, content: string): {
+    submit(sideChatId: string, clientInstanceId: string, input: {
+        content: string;
+        attachments?: UserTurnAttachment[];
+    }): {
         runId: string;
     };
     abort(sideChatId: string, clientInstanceId: string, runId?: string): Promise<boolean>;

package/dist/src/gateway/side-chat/run-service.js

@@ -12,9 +12,9 @@ var SideChatRunService = class {
 	constructor(options) {
 		this.options = options;
 	}
-	submit(sideChatId, clientInstanceId, content) {
-		const text = content.trim();
-		if (!text) throw new SideChatError("content is required", "INVALID_REQUEST");
+	submit(sideChatId, clientInstanceId, input) {
+		const text = input.content.trim();
+		if (!text && !input.attachments?.length) throw new SideChatError("content or attachments are required", "INVALID_REQUEST");
 		const sideChat = this.options.manager.get(sideChatId, clientInstanceId);
 		if (this.activeBySideChat.has(sideChatId)) throw new SideChatError("A side chat run is already active", "CONFLICT");
 		const run = {
@@ -26,7 +26,10 @@ var SideChatRunService = class {
 		};
 		this.activeBySideChat.set(sideChatId, run);
 		this.options.manager.setStatus(sideChatId, clientInstanceId, "running", run.runId);
-		this.execute(run, text, sideChat.config).catch((err) => {
+		this.execute(run, {
+			content: text,
+			attachments: input.attachments
+		}, sideChat.config).catch((err) => {
 			log.error({
 				err,
 				sideChatId,
@@ -55,11 +58,11 @@ var SideChatRunService = class {
 	}
 	submitClarification(sideChatId, clientInstanceId, requestId, answer) {
 		if (this.options.manager.get(sideChatId, clientInstanceId).clarification?.requestId !== requestId) return false;
-		const handled = this.options.agentRunner.submitClarifyResponse(requestId, answer);
+		const handled = this.options.agentRunner.answerEphemeralClarification(requestId, answer);
 		if (handled) this.options.manager.setStatus(sideChatId, clientInstanceId, "running");
 		return handled;
 	}
-	async execute(run, content, config) {
+	async execute(run, input, config) {
 		const topic = `run:${run.runId}`;
 		const mapper = new ChatStreamMapper({
 			runId: run.runId,
@@ -73,8 +76,10 @@ var SideChatRunService = class {
 			if (run.abortController.signal.aborted) return;
 			if (event.type === "clarify_request") this.options.manager.waitForInput(run.sideChatId, run.clientInstanceId, {
 				requestId: String(event.requestId),
+				kind: event.kind === "approval" ? "approval" : "input",
 				question: String(event.question),
-				choices: Array.isArray(event.choices) ? event.choices.filter((choice) => typeof choice === "string") : void 0
+				choices: Array.isArray(event.choices) ? event.choices.filter((choice) => typeof choice === "string") : void 0,
+				suggestedAnswer: typeof event.suggestedAnswer === "string" ? event.suggestedAnswer : void 0
 			}, event.kind === "approval" ? "waiting-approval" : "waiting-input");
 			for (const mapped of mapper.map(event)) publish(mapped);
 		};
@@ -82,28 +87,24 @@ var SideChatRunService = class {
 			for (const event of mapper.start()) publish(event);
 			publishMapped({
 				type: "user_message",
-				message: {
-					role: "user",
-					content,
-					timestamp: Date.now()
-				}
+				content: input.content,
+				media: input.attachments?.map(({ data: _data, ...attachment }) => attachment),
+				timestamp: Date.now()
 			});
-			this.options.agentRunner.registerExternalWebchatRun(run.executionSessionKey, run.runId, (event) => publishMapped(event), {
-				clarificationTimeoutMs: null,
-				beforeClarificationResponse: () => {
-					try {
-						this.options.manager.setStatus(run.sideChatId, run.clientInstanceId, "running");
-						return true;
-					} catch {
-						return false;
-					}
+			this.options.agentRunner.registerExternalWebchatRun(run.executionSessionKey, run.runId, (event) => publishMapped(event), { beforeClarificationResponse: () => {
+				try {
+					this.options.manager.setStatus(run.sideChatId, run.clientInstanceId, "running");
+					return true;
+				} catch {
+					return false;
 				}
-			});
+			} });
 			const result = await this.options.getAgentService().runEphemeralTurn({
 				executionSessionKey: run.executionSessionKey,
 				parentSessionKey: this.options.manager.get(run.sideChatId, run.clientInstanceId).parentSessionKey,
 				runId: run.runId,
-				content,
+				content: input.content,
+				attachments: input.attachments,
 				modelRef: config.modelRef,
 				thinkingLevel: config.thinkingLevel,
 				transcriptRuntime: this.options.manager.getRuntime(run.sideChatId, run.clientInstanceId),

package/dist/src/gateway/side-chat/types.d.ts

@@ -39,7 +39,7 @@ export interface SideChatContextSnapshot {
 }
 export interface SideChatConfig {
     modelRef: string;
-    thinkingLevel?: ThinkingLevel;
+    thinkingLevel: ThinkingLevel;
 }
 export interface SideChatView {
     id: string;
@@ -54,8 +54,10 @@ export interface SideChatView {
     runId?: string;
     clarification?: {
         requestId: string;
+        kind: 'input' | 'approval';
         question: string;
         choices?: string[];
+        suggestedAnswer?: string;
     };
     messageCount: number;
     context: SideChatContextSnapshot;

package/dist/src/heartbeat/index.js

@@ -1,6 +1,6 @@
 import { DEFAULT_ACK_MAX_CHARS, HEARTBEAT_OK, NO_REPLY, shouldSilence, stripHeartbeatToken } from "./tokens.js";
+import { appendCronEventLines } from "./event-prompt.js";
 import { isWithinActiveHours } from "./active-hours.js";
 import { isHeartbeatContentEmpty } from "./content-check.js";
-import { appendCronEventLines } from "./event-prompt.js";
 import { createHeartbeatWake } from "./wake.js";
 export { DEFAULT_ACK_MAX_CHARS, HEARTBEAT_OK, NO_REPLY, appendCronEventLines, createHeartbeatWake, isHeartbeatContentEmpty, isWithinActiveHours, shouldSilence, stripHeartbeatToken };

package/dist/src/platform/client.d.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { type PlatformDiscovery, type PlatformEvent } from './contracts.js';
+export declare const PLATFORM_RUNTIME_PROVIDER = "xopc-platform-runtime";
+export declare const PLATFORM_RUNTIME_PROFILE = "xopc-platform-runtime:default";
+export declare function discoverPlatform(baseUrl: string, fetchImpl?: typeof fetch): Promise<PlatformDiscovery>;
+export declare const RuntimeCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"run.start">;
+    payload: z.ZodObject<{
+        runId: z.ZodString;
+        traceId: z.ZodString;
+        agentVersionId: z.ZodString;
+        organizationId: z.ZodString;
+        workspaceId: z.ZodString;
+        runtimeId: z.ZodString;
+        manifest: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<"1">;
+            agentId: z.ZodString;
+            version: z.ZodString;
+            runtime: z.ZodObject<{
+                engine: z.ZodLiteral<"xopc">;
+                requires: z.ZodString;
+                execution: z.ZodArray<z.ZodEnum<{
+                    local: "local";
+                    managed: "managed";
+                    enterprise: "enterprise";
+                }>>;
+            }, z.core.$strict>;
+            entry: z.ZodObject<{
+                instructions: z.ZodString;
+                workflow: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            models: z.ZodObject<{
+                intents: z.ZodArray<z.ZodEnum<{
+                    review: "review";
+                    coding: "coding";
+                    understanding: "understanding";
+                    fast: "fast";
+                    reasoning: "reasoning";
+                    vision: "vision";
+                }>>;
+                allow: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
+            dependencies: z.ZodObject<{
+                skills: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    version: z.ZodString;
+                    sha256: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>;
+                connectors: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    version: z.ZodString;
+                    sha256: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>;
+                extensions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    version: z.ZodString;
+                    sha256: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>;
+            permissions: z.ZodObject<{
+                tools: z.ZodArray<z.ZodString>;
+                networkDomains: z.ZodArray<z.ZodString>;
+                filesystem: z.ZodArray<z.ZodString>;
+                effects: z.ZodArray<z.ZodEnum<{
+                    delete: "delete";
+                    read: "read";
+                    write: "write";
+                    execute: "execute";
+                    admin: "admin";
+                    send: "send";
+                    purchase: "purchase";
+                    publish: "publish";
+                }>>;
+            }, z.core.$strict>;
+            data: z.ZodObject<{
+                classification: z.ZodEnum<{
+                    public: "public";
+                    internal: "internal";
+                    confidential: "confidential";
+                    restricted: "restricted";
+                }>;
+                memory: z.ZodEnum<{
+                    workspace: "workspace";
+                    none: "none";
+                    local: "local";
+                }>;
+                retentionPolicy: z.ZodString;
+            }, z.core.$strict>;
+            quality: z.ZodObject<{
+                evaluationSuite: z.ZodOptional<z.ZodString>;
+                releaseGate: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+    }, z.core.$loose>;
+    id: z.ZodString;
+    runId: z.ZodString;
+    leaseToken: z.ZodString;
+    leaseExpiresAt: z.ZodNumber;
+}, z.core.$strict>;
+export type RuntimeCommand = z.infer<typeof RuntimeCommandSchema>;
+declare const runtimeRenewalResponseSchema: z.ZodObject<{
+    leaseExpiresAt: z.ZodNumber;
+    cancelRequested: z.ZodBoolean;
+}, z.core.$strict>;
+export type RuntimeLeaseRenewal = z.infer<typeof runtimeRenewalResponseSchema>;
+export declare class PlatformRuntimeClient {
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly agentApi;
+    constructor(discovery: PlatformDiscovery, token: string, fetchImpl?: typeof fetch);
+    private request;
+    heartbeat(input?: {
+        capabilities?: Record<string, unknown>;
+        endpoint?: string;
+        leaseSeconds?: number;
+    }): Promise<Record<string, unknown>>;
+    lease(leaseSeconds?: number): Promise<RuntimeCommand | null>;
+    report(event: PlatformEvent, leaseToken?: string): Promise<'accepted' | 'duplicate'>;
+    renew(commandId: string, leaseToken: string, leaseSeconds?: number): Promise<RuntimeLeaseRenewal>;
+}
+export {};

package/dist/src/platform/client.js

@@ -0,0 +1,108 @@
+import { AgentManifestSchema, PlatformDiscoverySchema, PlatformEventSchema, init_contracts } from "./contracts.js";
+import { z } from "zod";
+//#region src/platform/client.ts
+init_contracts();
+const PLATFORM_RUNTIME_PROVIDER = "xopc-platform-runtime";
+const PLATFORM_RUNTIME_PROFILE = "xopc-platform-runtime:default";
+function trimBaseUrl(value) {
+	const url = new URL(value);
+	url.hash = "";
+	url.search = "";
+	url.pathname = url.pathname.replace(/\/+$/, "");
+	return url.toString().replace(/\/+$/, "");
+}
+async function responseJson(response) {
+	return response.json().catch(() => null);
+}
+async function discoverPlatform(baseUrl, fetchImpl = fetch) {
+	const response = await fetchImpl(`${trimBaseUrl(baseUrl)}/.well-known/xopc-platform`, {
+		headers: { accept: "application/json" },
+		signal: AbortSignal.timeout(15e3)
+	});
+	if (!response.ok) throw new Error(`Platform discovery failed with HTTP ${response.status}`);
+	return PlatformDiscoverySchema.parse(await responseJson(response));
+}
+const runtimeIdentifier = z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+const runtimeCommandBase = {
+	id: runtimeIdentifier,
+	runId: runtimeIdentifier,
+	leaseToken: z.string().min(1).max(512),
+	leaseExpiresAt: z.number().int().positive()
+};
+const RuntimeCommandSchema = z.object({
+	...runtimeCommandBase,
+	type: z.literal("run.start"),
+	payload: z.object({
+		runId: runtimeIdentifier,
+		traceId: runtimeIdentifier,
+		agentVersionId: runtimeIdentifier,
+		organizationId: runtimeIdentifier,
+		workspaceId: runtimeIdentifier,
+		runtimeId: runtimeIdentifier,
+		manifest: AgentManifestSchema
+	}).passthrough()
+}).strict().superRefine((command, context) => {
+	if (command.payload.runId !== command.runId) context.addIssue({
+		code: z.ZodIssueCode.custom,
+		message: "Runtime command run identity does not match its payload",
+		path: ["payload", "runId"]
+	});
+});
+const runtimeLeaseResponseSchema = z.object({ command: RuntimeCommandSchema }).strict();
+const runtimeRenewalResponseSchema = z.object({
+	leaseExpiresAt: z.number().int().positive(),
+	cancelRequested: z.boolean()
+}).strict();
+var PlatformRuntimeClient = class {
+	agentApi;
+	constructor(discovery, token, fetchImpl = fetch) {
+		this.token = token;
+		this.fetchImpl = fetchImpl;
+		if (!discovery.capabilities.runtimeFleet || !discovery.endpoints.agentApi) throw new Error("Connected platform does not provide a runtime fleet");
+		this.agentApi = discovery.endpoints.agentApi.replace(/\/+$/, "");
+		if (!token.startsWith("xopc_rt_")) throw new Error("Invalid platform runtime token");
+	}
+	async request(path, body) {
+		return this.fetchImpl(`${this.agentApi}${path}`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${this.token}`,
+				"content-type": "application/json",
+				accept: "application/json"
+			},
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(3e4)
+		});
+	}
+	async heartbeat(input = {}) {
+		const response = await this.request("/heartbeat", input);
+		if (!response.ok) throw new Error(`Runtime heartbeat failed with HTTP ${response.status}`);
+		return await responseJson(response);
+	}
+	async lease(leaseSeconds = 30) {
+		const response = await this.request("/lease", { leaseSeconds });
+		if (response.status === 204) return null;
+		if (!response.ok) throw new Error(`Runtime lease failed with HTTP ${response.status}`);
+		return runtimeLeaseResponseSchema.parse(await responseJson(response)).command;
+	}
+	async report(event, leaseToken) {
+		const response = await this.request("/events", {
+			event: PlatformEventSchema.parse(event),
+			leaseToken
+		});
+		if (!response.ok) throw new Error(`Runtime event failed with HTTP ${response.status}`);
+		const value = await responseJson(response);
+		if (value?.status !== "accepted" && value?.status !== "duplicate") throw new Error("Runtime event response is incomplete");
+		return value.status;
+	}
+	async renew(commandId, leaseToken, leaseSeconds = 60) {
+		const response = await this.request(`/commands/${encodeURIComponent(commandId)}/renew`, {
+			leaseToken,
+			leaseSeconds
+		});
+		if (!response.ok) throw new Error(`Runtime lease renewal failed with HTTP ${response.status}`);
+		return runtimeRenewalResponseSchema.parse(await responseJson(response));
+	}
+};
+//#endregion
+export { PLATFORM_RUNTIME_PROFILE, PLATFORM_RUNTIME_PROVIDER, PlatformRuntimeClient, RuntimeCommandSchema, discoverPlatform };