maka-agent 0.2.0-dev.26.20260909 → 0.2.0-dev.28.20260911

package/node_modules/@maka/runtime-host/dist/server/execution-composition.js

@@ -18,7 +18,7 @@
  */
 import { copyWorkHubAttachmentsToTarget } from './workhub-message-attachments.js';
 import { createHash, randomUUID } from 'node:crypto';
-import { MAX_READ_IMAGE_BYTES } from '@maka/core/attachments';
+import { attachmentKindFromMimeType, MAX_READ_IMAGE_BYTES } from '@maka/core/attachments';
 import { messageContentDigest, normalizeMessageContent } from '@maka/core/events';
 import { NO_REAL_CONNECTION_CODE } from '@maka/core/connection-error-copy';
 import { generalizedErrorMessage } from '@maka/core/redaction';
@@ -26,11 +26,12 @@ import { emptyPlanSessionState } from '@maka/core/plan';
 import { readLogicalRuntimeExecutionForRun } from '@maka/core/runtime-logical-execution';
 import { runtimeInvocationOutcome, } from '@maka/core/runtime-invocation';
 import { isDeepResearchSession, WORKHUB_COORDINATION_SESSION_ID, WORKHUB_COORDINATION_REPLACEMENT_SCHEMA_VERSION, } from '@maka/core/session';
-import { AgentGraphCoordinator } from '@maka/runtime/stream-graph-coordinator';
+import { AgentGraphClientOperationError, AgentGraphCoordinator, } from '@maka/runtime/stream-graph-coordinator';
 import { AgentGraphSupervisorWakeCoordinator } from '@maka/runtime/agent-graph-supervisor-wake';
 import { BackendRegistry, SessionManager, workHubDirectStopAbortSource, } from '@maka/runtime/session-manager';
 import { buildToolsForAgentDefinition } from '@maka/runtime/agent-catalog';
 import { buildHistoryTools } from '@maka/runtime/history-tools';
+import { buildBuiltinTools } from '@maka/runtime/builtin-tools';
 import { createLocalContinuationSafetyInspector } from '@maka/runtime/continuation-safety';
 import { createConfiguredSubagentCatalog } from '@maka/runtime/configured-subagent-catalog';
 import { buildHostCapabilitiesFromBinding } from '@maka/runtime/skills';
@@ -45,8 +46,24 @@ import { SessionActivityRegistry } from '@maka/runtime/goal-turn-lifecycle';
 import { ShellRunProcessManager } from '@maka/runtime/shell-run-manager';
 import { resolveShellPlan, resolveTurnShellPlan, validateShellPreference, } from '@maka/runtime/shell-detect';
 import { Context } from '@maka/runtime/plugin-kernel';
+import { PluginAgentService } from '@maka/runtime/plugin-agent-service';
+import { PluginAttachmentService } from '@maka/runtime/plugin-attachment-service';
+import { PluginApprovalService } from '@maka/runtime/plugin-approval-service';
+import { PluginFilesystemService } from '@maka/runtime/plugin-fs-service';
+import { PluginLlmService } from '@maka/runtime/plugin-llm-service';
+import { PluginShellService } from '@maka/runtime/plugin-shell-service';
+import { PluginUserQuestionService } from '@maka/runtime/plugin-user-question-service';
+import { PluginWebService } from '@maka/runtime/plugin-web-service';
 import { MakaCompositionLoader } from '@maka/runtime/plugin-composition-loader';
 import { PluginToolService } from '@maka/runtime/plugin-tool-service';
+import { PluginSystemPromptService } from '@maka/runtime/plugin-system-prompt-service';
+import { PluginCommandService } from '@maka/runtime/plugin-command-service';
+import { PluginAuthorizationService, PluginCredentialService, PluginSettingsService, PluginStorageService, } from '@maka/runtime/plugin-data-services';
+import { PluginGoalService } from '@maka/runtime/plugin-goal-service';
+import { PluginLspService } from '@maka/runtime/plugin-lsp-service';
+import { PluginSessionQueryService } from '@maka/runtime/plugin-session-query-service';
+import { PluginShellEnvService } from '@maka/runtime/plugin-shell-env-service';
+import { PluginSkillService } from '@maka/runtime/plugin-skill-service';
 import { isHostedExecutionTerminal } from './hosted-execution-authority.js';
 import { createAgentGraphControlStore } from '@maka/storage/agent-graph-control-store';
 import { createArtifactAttachmentResourceReader } from '@maka/storage/artifact-stores';
@@ -59,6 +76,7 @@ import { createInteractiveContextOffloadReader } from '@maka/storage/context-off
 import { openStorageWriterComposition } from '@maka/storage/storage-writer-composition';
 import { resolveWorkspaceIdentity } from '@maka/storage/workspace-identity';
 import { CanonicalSessionProjectionReader } from './canonical-session-projection.js';
+import { HostPluginDataRuntime } from './plugin-data-runtime.js';
 import { bindHostChildAgentBackend, createHostChildAgentToolComposition, } from './child-agent-composition.js';
 import { HostCanonicalPermissionOutcomeReader } from './canonical-permission-outcome-reader.js';
 import { HostArtifactCoordinator } from './artifact-coordinator.js';
@@ -75,7 +93,7 @@ import { HostDeepResearchCoordinator } from './deep-research-coordinator.js';
 import { HostDailyReviewCoordinator } from './daily-review-coordinator.js';
 import { prepareHostAiSdkBackend } from './execution-model-composition.js';
 import { createInteractiveRunComposer, createInteractiveRunComposerFactory, routeInteractiveRunToolSurface, } from './interactive-run-composer.js';
-import { createHostGoalEvaluator, createHostDailyReviewModel, createHostMemoryExtractionModel, createHostSessionEffectModel, } from './execution-model-authority.js';
+import { createHostGoalEvaluator, createHostDailyReviewModel, createHostMemoryExtractionModel, createHostPluginModel, createHostSessionEffectModel, } from './execution-model-authority.js';
 import { HostExecutionInspectCoordinator } from './execution-inspect-coordinator.js';
 import { HostExternalSessionCoordinator } from './external-session-coordinator.js';
 import { HostGoalCoordinator } from './goal-coordinator.js';
@@ -88,7 +106,7 @@ import { HostInteractionCoordinator } from './interaction-coordinator.js';
 import { HostInteractiveTurnCoordinator } from './interactive-turn-coordinator.js';
 import { SessionTurnAccessRequestCoordinator } from './session-turn-access-request-coordinator.js';
 import { ensureBootstrapRuntimePolicy } from './bootstrap-runtime-policy.js';
-import { hostedExecutionRunProfile } from './hosted-execution-tool-profile.js';
+import { bindWorkHubRoutingDecisionPrompt, hostedExecutionRunProfile, } from './hosted-execution-tool-profile.js';
 import { HostMemoryCoordinator } from './memory-coordinator.js';
 import { HostMemoryExtractionCoordinator } from './memory-extraction-coordinator.js';
 import { MemoryExtractionSessionLane } from './memory-extraction-session-lane.js';
@@ -118,7 +136,7 @@ import { HostSessionRevisionCoordinator } from './session-revision-coordinator.j
 import { HostSessionEffectCoordinator } from './session-effect-coordinator.js';
 import { SessionContinuityCoordinator } from './session-continuity-coordinator.js';
 import { createSessionTranscriptReader, } from './session-transcript-reader.js';
-import { HostSkillCatalogCoordinator } from './skill-catalog-coordinator.js';
+import { HostSkillCatalogCoordinator, SkillCatalogInvocableContextError, } from './skill-catalog-coordinator.js';
 import { SkillCatalogRepository } from './skill-catalog-repository.js';
 import { HostSessionTodoCoordinator } from './session-todo-coordinator.js';
 import { HostTurnControlCoordinator } from './turn-control-coordinator.js';
@@ -177,10 +195,35 @@ export async function createExecutionRuntimeHostComposition(context, options = {
     let archiveEvidence;
     try {
         const pluginRoot = new Context();
-        const pluginTools = new PluginToolService(pluginRoot);
+        const pluginAgents = new PluginAgentService(pluginRoot);
+        const pluginAttachments = new PluginAttachmentService(pluginRoot, pluginAgents);
+        new PluginApprovalService(pluginRoot, pluginAgents);
+        new PluginUserQuestionService(pluginRoot, pluginAgents);
+        const pluginFilesystem = new PluginFilesystemService(pluginRoot, pluginAgents);
+        const pluginLlm = new PluginLlmService(pluginRoot, pluginAgents);
+        const pluginShellEnv = new PluginShellEnvService(pluginRoot);
+        const pluginShell = new PluginShellService(pluginRoot, pluginAgents, pluginShellEnv);
+        const pluginWeb = new PluginWebService(pluginRoot, pluginAgents);
+        const pluginSessionQuery = new PluginSessionQueryService(pluginRoot, pluginAgents);
+        const pluginGoals = new PluginGoalService(pluginRoot, pluginAgents);
+        const pluginSkills = new PluginSkillService(pluginRoot);
+        const pluginCommands = new PluginCommandService(pluginRoot);
+        new PluginLspService(pluginRoot);
+        const pluginSettings = new PluginSettingsService(pluginRoot);
+        const pluginStorage = new PluginStorageService(pluginRoot);
+        const pluginCredentials = new PluginCredentialService(pluginRoot);
+        new PluginAuthorizationService(pluginRoot, pluginCredentials);
+        const pluginData = new HostPluginDataRuntime(context.owner.controlDirectory);
+        pluginSettings.bindRuntime(pluginData);
+        pluginStorage.bindRuntime(pluginData);
+        pluginCredentials.bindRuntime(pluginData);
+        const pluginTools = new PluginToolService(pluginRoot, { agents: pluginAgents });
+        const pluginSystemPrompt = new PluginSystemPromptService(pluginRoot);
         pluginPlatform = new HostPluginPlatform(context.owner.controlDirectory, {
             composition: new MakaCompositionLoader({ root: pluginRoot }),
             tools: pluginTools,
+            systemPrompt: pluginSystemPrompt,
+            commands: pluginCommands,
         });
         const pluginPlatformCoordinator = new HostPluginPlatformCoordinator(pluginPlatform);
         const openedProjectCatalog = storage.projectCatalog;
@@ -323,12 +366,94 @@ export async function createExecutionRuntimeHostComposition(context, options = {
             ...(sandboxManager ? { sandboxManager } : {}),
             ...(filesystemWorker ? { filesystemWorker } : {}),
         };
+        const invokeBuiltin = async (name, args, invocation, shellEnvironment) => {
+            if (!invocation.toolContext)
+                throw new Error(`${name} requires an active Tool invocation`);
+            const policy = await runtimePolicyStores.runtimePolicy.getSnapshot();
+            const tool = buildBuiltinTools({
+                ...builtinTools,
+                shell: resolveTurnShellPlan(policy.policy.shell),
+                ...(shellEnvironment ? { shellEnvironment } : {}),
+            }).find((candidate) => candidate.name === name);
+            if (!tool)
+                throw new Error(`Builtin capability is unavailable: ${name}`);
+            return tool.impl(args, invocation.toolContext);
+        };
+        pluginFilesystem.bindRuntime({
+            execute: (operation, invocation) => {
+                switch (operation.kind) {
+                    case 'read':
+                        return invokeBuiltin('Read', operation, invocation);
+                    case 'write':
+                        return invokeBuiltin('Write', operation, invocation);
+                    case 'edit':
+                        return invokeBuiltin('Edit', {
+                            path: operation.path,
+                            old_string: operation.oldString,
+                            new_string: operation.newString,
+                        }, invocation);
+                    case 'glob':
+                        return invokeBuiltin('Glob', { pattern: operation.pattern, cwd: operation.path }, invocation);
+                    case 'grep':
+                        return invokeBuiltin('Grep', { pattern: operation.pattern, path: operation.path, glob: operation.glob }, invocation);
+                    case 'apply_patch':
+                        return invokeBuiltin('apply_patch', operation.patch, invocation);
+                }
+            },
+        });
+        pluginShell.bindRuntime({
+            run: (options, invocation) => invokeBuiltin('Bash', {
+                command: options.command,
+                timeout_ms: options.timeoutMs,
+                run_in_background: options.background,
+                pty: options.pty,
+            }, invocation, options.environment),
+            read: (ref, invocation) => runtimeResources.readRuntimeResource(invocation.sessionId, ref, invocation.abortSignal),
+            write: (ref, input, invocation) => runtimeResources.writeStdin({
+                sessionId: invocation.sessionId,
+                ref,
+                input,
+                abortSignal: invocation.abortSignal,
+                caller: 'model',
+            }),
+            stop: (ref, invocation) => runtimeResources.stopBackgroundTask(invocation.sessionId, ref, invocation.abortSignal),
+        });
+        pluginAttachments.bindRuntime({
+            create: async (input, invocation) => {
+                const record = await openedArtifactStore.create({
+                    sessionId: invocation.sessionId,
+                    turnId: invocation.turnId,
+                    name: input.name,
+                    kind: pluginAttachmentArtifactKind(input.mimeType, input.name),
+                    content: input.content,
+                    mimeType: input.mimeType,
+                    source: 'tool_result',
+                    ...(input.summary ? { summary: input.summary } : {}),
+                });
+                return pluginAttachmentRef(record);
+            },
+            read: async (attachment, invocation) => {
+                if (attachment.ref.kind !== 'session_file' ||
+                    attachment.ref.sessionId !== invocation.sessionId) {
+                    throw new Error('Attachment is outside the current Session');
+                }
+                const result = await openedArtifactStore.readBinaryInSession(invocation.sessionId, attachment.ref.relativePath);
+                if (!result.ok)
+                    throw new Error(`Attachment read failed: ${result.reason}`);
+                return Uint8Array.from(Buffer.from(result.base64, 'base64'));
+            },
+            list: async (invocation) => (await openedArtifactStore.listTurnArtifacts(invocation.sessionId, invocation.turnId)).map(pluginAttachmentRef),
+        });
         const webSearchService = createHostWebSearchService({
             policy: runtimePolicyStores.operations,
         });
         const webFetchService = createHostWebFetchService({
             policy: runtimePolicyStores.operations,
         });
+        pluginWeb.bindRuntime({
+            search: ({ query, limit, abortSignal }) => webSearchService.search({ query, limit, ...(abortSignal ? { abortSignal } : {}) }),
+            fetch: (input) => webFetchService.fetch(input),
+        });
         const historyTools = buildHistoryTools({
             listSessions: () => requireSessionManager(manager).listSessions(),
             readMessages: async (sessionId, abortSignal) => {
@@ -375,8 +500,33 @@ export async function createExecutionRuntimeHostComposition(context, options = {
         }), workspaceResolver, async (input, connection) => {
             if (input.target.kind === 'session') {
                 const sessionId = input.target.sessionId;
-                const header = await stores.sessionStore.readHeaderSnapshot(sessionId);
-                const preview = await requireClientCapabilities(clientCapabilities).runWithSessionBindingPreview(sessionId, connection.connectionId, () => requireToolNameResolver(resolveAvailableToolNames)(sessionId));
+                let header;
+                try {
+                    header = await stores.sessionStore.readHeaderSnapshot(sessionId);
+                }
+                catch (error) {
+                    if (isSessionNotFoundError(error)) {
+                        throw new SkillCatalogInvocableContextError('not_found', 'Session does not exist');
+                    }
+                    throw error;
+                }
+                if (header.isArchived) {
+                    throw new SkillCatalogInvocableContextError('session_archived', 'Session is archived');
+                }
+                let preview;
+                try {
+                    preview = await requireClientCapabilities(clientCapabilities).runWithSessionBindingPreview(sessionId, connection.connectionId, () => requireToolNameResolver(resolveAvailableToolNames)(sessionId));
+                }
+                catch (error) {
+                    if (isSessionNotFoundError(error)) {
+                        throw new SkillCatalogInvocableContextError('not_found', 'Session does not exist');
+                    }
+                    if (error instanceof AgentGraphClientOperationError &&
+                        error.code === 'session_archived') {
+                        throw new SkillCatalogInvocableContextError('session_archived', 'Session is archived');
+                    }
+                    throw error;
+                }
                 if (!preview.ok)
                     throw new Error(preview.message);
                 return {
@@ -394,6 +544,7 @@ export async function createExecutionRuntimeHostComposition(context, options = {
             publish: (sessionId) => hostChanges.publishSessionCatalog(sessionId),
         }, projectMembership, context.requestDrain, new HostProjectDirectoryAuthority(options.projectDirectoryRoots));
         let rootCoordinator;
+        let workHubCoordination;
         let canonicalProjection;
         let memory;
         let clientCapabilities;
@@ -473,6 +624,7 @@ export async function createExecutionRuntimeHostComposition(context, options = {
         let recoveryTask;
         let rootCloseTask;
         let rootRecoveryCompleted = false;
+        let clientBoundRecovery = Promise.resolve();
         let closeTask;
         let backendInvalidationPoisoned = false;
         let domainModules;
@@ -539,6 +691,7 @@ export async function createExecutionRuntimeHostComposition(context, options = {
             oauthCredentials,
             createRunComposer: createInteractiveRunComposerFactory({
                 skills,
+                pluginSkills,
                 memory: requireMemory(memory),
                 sessionTodo,
                 clientCapabilities: requireClientCapabilities(clientCapabilities),
@@ -551,9 +704,29 @@ export async function createExecutionRuntimeHostComposition(context, options = {
                 hostTools,
                 resolveRootTools: (sessionId) => requireGraphCoordinator(graphCoordinator).toolsForSession(sessionId),
                 resolvePluginTools: (sessionId, coreTools) => pluginTools.resolveContributions(sessionId, coreTools),
+                resolvePluginSystemPrompt: async (sessionId, promptContext, baseText) => {
+                    const assembly = await pluginSystemPrompt.assemble({
+                        sessionId,
+                        turnId: promptContext.turnId,
+                        cwd: promptContext.cwd,
+                    }, baseText);
+                    return {
+                        text: assembly.text,
+                        contexts: assembly.contexts,
+                        sourceRevisions: assembly.sourceRevision ? [assembly.sourceRevision] : [],
+                    };
+                },
                 parentAgentTools: childAgentTools.parentTools,
                 childTools: childAgentTools.childTools,
                 worktreePatchWriteBackAvailable: true,
+                resolveProfileSystemPrompt: async (promptContext, basePrompt) => {
+                    if (promptContext.sessionId !== WORKHUB_COORDINATION_SESSION_ID)
+                        return basePrompt;
+                    const admission = await stores.agentRunStore.readRootTurnAdmission(promptContext.sessionId, promptContext.turnId);
+                    return bindWorkHubRoutingDecisionPrompt(basePrompt, admission?.execution.kind === 'workhub_coordination'
+                        ? admission.execution.routingDecision
+                        : undefined);
+                },
             }),
             ...(hostedExecutionRunProfile(backendContext.header.toolProfile)?.memoryExtraction === false
                 ? {}
@@ -927,8 +1100,229 @@ export async function createExecutionRuntimeHostComposition(context, options = {
         }, {
             currentGraphId: (rootSessionId) => requireGraphCoordinator(graphCoordinator).currentGraphId(rootSessionId),
             beginNextGraphEpoch: async (rootSessionId) => (await requireGraphCoordinator(graphCoordinator).beginNextGraphEpoch(rootSessionId, (operation) => requireGraphSupervisorWake(graphSupervisorWake).runWithSessionWakesSuppressed(rootSessionId, operation, 'agent_graph_epoch_advanced'))).graphId,
-        }, (input) => sessionEffectCoordinator.nameSessionFromRootMessage(input), context.owner.capability.rootId);
+        }, (input) => sessionEffectCoordinator.nameSessionFromRootMessage(input), context.owner.capability.rootId, dependencies.workHubRoutingModel
+            ? (input) => workHubCoordination.prepareRoutingDecision(input)
+            : undefined);
         const coordinator = rootCoordinator;
+        const pluginModel = createHostPluginModel({
+            runtimePolicy: runtimePolicyStores,
+            oauthCredentials,
+            usage: openedUsageStores,
+            requestDrain: context.requestDrain,
+            readSessionHeader: (sessionId) => stores.sessionStore.readHeaderSnapshot(sessionId),
+        });
+        pluginLlm.bindRuntime({
+            generate: (input, invocation) => pluginModel.generate({
+                sessionId: invocation.sessionId,
+                prompt: input.prompt,
+                ...(input.system ? { system: input.system } : {}),
+                ...(input.maxOutputTokens ? { maxOutputTokens: input.maxOutputTokens } : {}),
+                abortSignal: input.signal ?? invocation.abortSignal,
+            }),
+        });
+        const visibleAgentSessions = async (initiator) => {
+            const sessions = await manager.listSessions();
+            if (!initiator)
+                return [];
+            const visible = new Set([initiator.sessionId]);
+            let changed = true;
+            while (changed) {
+                changed = false;
+                for (const session of sessions) {
+                    if (!session.parentSessionId ||
+                        !visible.has(session.parentSessionId) ||
+                        visible.has(session.id))
+                        continue;
+                    visible.add(session.id);
+                    changed = true;
+                }
+            }
+            return sessions.filter((session) => visible.has(session.id));
+        };
+        const pluginSessionSummary = (session) => Object.freeze({
+            id: session.id,
+            ...(session.name ? { title: session.name } : {}),
+            ...(session.cwd ? { cwd: session.cwd } : {}),
+            ...(session.status ? { status: session.status } : {}),
+            ...(session.parentSessionId ? { parentSessionId: session.parentSessionId } : {}),
+            ...(session.statusUpdatedAt || session.lastMessageAt
+                ? { updatedAt: session.statusUpdatedAt ?? session.lastMessageAt }
+                : {}),
+        });
+        const sessionQueryInitiator = (caller) => caller.invocation ??
+            (caller.scopeSessionId ? Object.freeze({ sessionId: caller.scopeSessionId }) : undefined);
+        pluginSessionQuery.bindRuntime({
+            list: async (caller) => Object.freeze((await visibleAgentSessions(sessionQueryInitiator(caller))).map(pluginSessionSummary)),
+            read: async (sessionId, caller) => {
+                const session = (await visibleAgentSessions(sessionQueryInitiator(caller))).find(({ id }) => id === sessionId);
+                if (!session)
+                    return undefined;
+                return Object.freeze({
+                    session: pluginSessionSummary(session),
+                    messages: Object.freeze([
+                        ...(await requireSessionManager(manager).getMessages(sessionId)),
+                    ]),
+                });
+            },
+            search: async (request, caller) => {
+                const query = request.query.toLocaleLowerCase();
+                const sessions = await visibleAgentSessions(sessionQueryInitiator(caller));
+                const matches = [];
+                for (const session of sessions) {
+                    const headerText = `${session.name}\n${session.cwd ?? ''}`.toLocaleLowerCase();
+                    if (headerText.includes(query)) {
+                        matches.push(session);
+                        continue;
+                    }
+                    const messages = await requireSessionManager(manager).getMessages(session.id);
+                    if (messages.some((message) => JSON.stringify(message).toLocaleLowerCase().includes(query))) {
+                        matches.push(session);
+                    }
+                }
+                const offset = request.cursor ? Number.parseInt(request.cursor, 10) : 0;
+                if (!Number.isSafeInteger(offset) || offset < 0)
+                    throw new TypeError('Invalid Session query cursor');
+                const limit = request.limit ?? 20;
+                const page = matches.slice(offset, offset + limit);
+                return Object.freeze({
+                    items: Object.freeze(page.map(pluginSessionSummary)),
+                    ...(offset + page.length < matches.length
+                        ? { cursor: String(offset + page.length) }
+                        : {}),
+                });
+            },
+        });
+        const describeAgent = (session) => ({
+            id: session.id,
+            sessionId: session.id,
+            root: !session.parentSessionId,
+            status: session.runningTurnIds?.length ? 'running' : session.status,
+            ...(session.parentSessionId ? { ownerId: session.parentSessionId } : {}),
+        });
+        const submitAgentMessage = async (id, message, placement, initiator) => {
+            if (!(await visibleAgentSessions(initiator)).some((session) => session.id === id)) {
+                throw new Error('Agent is outside the current ownership tree');
+            }
+            const content = normalizeMessageContent(typeof message === 'string' ? { text: message } : message);
+            const result = await messages.handlers['turn.message.submit']({
+                originHostEpoch: context.hostEpoch,
+                sessionId: id,
+                messageId: randomUUID(),
+                content,
+                placement,
+            }, {
+                hostEpoch: context.hostEpoch,
+                connectionId: 'plugin-agent',
+                principal: 'runtime_host',
+                acquireResidency: () => context.acquireResidency('plugin-agent'),
+            });
+            if (!result.ok)
+                throw new Error(result.error.message);
+            return result.result;
+        };
+        pluginAgents.bindRuntime({
+            create: async (options, initiator) => {
+                const spawn = initiator.toolContext?.spawnChildSession;
+                if (!spawn)
+                    throw new Error('Agent creation requires an active Tool invocation');
+                if (!options.prompt?.trim())
+                    throw new Error('Agent creation requires a prompt');
+                return new Promise((resolve, reject) => {
+                    void spawn({
+                        agentProfile: options.agentProfile ?? 'implementation',
+                        prompt: options.prompt,
+                        ...(options.signal ? { abortSignal: options.signal } : {}),
+                        onReady: (ready) => resolve({
+                            id: ready.childSessionId,
+                            sessionId: ready.childSessionId,
+                            root: false,
+                            status: 'running',
+                            ownerId: initiator.sessionId,
+                        }),
+                    }).catch(reject);
+                });
+            },
+            resume: async (options, initiator) => {
+                if (options.prompt)
+                    await submitAgentMessage(options.sessionId, options.prompt, 'next_turn', initiator);
+                const session = (await visibleAgentSessions(initiator)).find((item) => item.id === options.sessionId);
+                if (!session)
+                    throw new Error('Agent was not found');
+                return describeAgent(session);
+            },
+            get: async (id, initiator) => {
+                const session = (await visibleAgentSessions(initiator)).find((item) => item.id === id);
+                return session ? describeAgent(session) : undefined;
+            },
+            list: async (initiator) => (await visibleAgentSessions(initiator)).map(describeAgent),
+            roots: async (initiator) => (await visibleAgentSessions(initiator))
+                .filter((session) => !session.parentSessionId)
+                .map(describeAgent),
+            followup: (id, message, initiator) => submitAgentMessage(id, message, 'next_turn', initiator),
+            steer: (id, message, initiator) => submitAgentMessage(id, message, 'current_turn', initiator),
+            inject: (id, message, initiator) => submitAgentMessage(id, message, 'current_turn', initiator),
+            cancel: async (id, initiator) => {
+                if (!(await visibleAgentSessions(initiator)).some((session) => session.id === id)) {
+                    throw new Error('Agent is outside the current ownership tree');
+                }
+                await coordinator.stopSession(id, { source: 'stop_button' });
+            },
+            whenIdle: async (id, signal, initiator) => {
+                if (!(await visibleAgentSessions(initiator)).some((session) => session.id === id)) {
+                    throw new Error('Agent is outside the current ownership tree');
+                }
+                const wait = coordinator.whenIdle(id);
+                if (!wait)
+                    return;
+                if (!signal)
+                    return wait;
+                if (signal.aborted)
+                    throw signal.reason;
+                let rejectAbort;
+                const aborted = new Promise((_resolve, reject) => {
+                    rejectAbort = reject;
+                });
+                const onAbort = () => rejectAbort?.(signal.reason);
+                signal.addEventListener('abort', onAbort, { once: true });
+                try {
+                    await Promise.race([wait, aborted]);
+                }
+                finally {
+                    signal.removeEventListener('abort', onAbort);
+                }
+            },
+            snapshot: async (id, initiator) => {
+                const session = (await visibleAgentSessions(initiator)).find((item) => item.id === id);
+                if (!session)
+                    throw new Error('Agent was not found');
+                return { agent: describeAgent(session), root: coordinator.readRootState(id) };
+            },
+            inbox: async (id, initiator) => {
+                if (!(await visibleAgentSessions(initiator)).some((session) => session.id === id))
+                    throw new Error('Agent was not found');
+                return coordinator.readRootState(id);
+            },
+            result: async (id, initiator) => {
+                if (!(await visibleAgentSessions(initiator)).some((session) => session.id === id))
+                    throw new Error('Agent was not found');
+                return (await manager.getMessages(id)).at(-1);
+            },
+            artifacts: async (id, initiator) => {
+                if (!(await visibleAgentSessions(initiator)).some((session) => session.id === id))
+                    throw new Error('Agent was not found');
+                return (await openedArtifactStore.listPage(id, { offset: 0, limit: 100 })).records;
+            },
+            transcript: async (id, initiator) => {
+                if (!(await visibleAgentSessions(initiator)).some((session) => session.id === id))
+                    throw new Error('Agent was not found');
+                return manager.getMessages(id);
+            },
+            dispose: async (id, initiator) => {
+                if (!(await visibleAgentSessions(initiator)).some((session) => session.id === id))
+                    throw new Error('Agent was not found');
+                await coordinator.stopSession(id, { source: 'stop_button' });
+            },
+        });
         const contextOperations = new HostContextCoordinator({
             runtime: manager,
             executions: coordinator,
@@ -1032,6 +1426,34 @@ export async function createExecutionRuntimeHostComposition(context, options = {
             onProjectionChanged: (sessionId) => continuityCoordinator.enqueueCanonicalRefresh(sessionId),
             requestDrain: context.requestDrain,
         });
+        pluginGoals.bindRuntime({
+            execute: async (operation, invocation) => {
+                const coordinator = requireGoal(goal);
+                if (operation.kind === 'get')
+                    return coordinator.readProjection(invocation.sessionId);
+                if (!invocation.toolContext)
+                    throw new Error('Goal mutation requires an active Tool invocation');
+                const toolName = operation.kind === 'create'
+                    ? 'GoalSet'
+                    : operation.kind === 'clear'
+                        ? 'GoalClear'
+                        : operation.kind === 'pause'
+                            ? 'GoalPause'
+                            : 'GoalResume';
+                const tool = coordinator.tools.find(({ name }) => name === toolName);
+                if (!tool)
+                    throw new Error(`Goal capability is unavailable: ${toolName}`);
+                const args = operation.kind === 'create'
+                    ? {
+                        condition: operation.objective,
+                        ...(operation.maxIterations ? { max_iterations: operation.maxIterations } : {}),
+                        ...(operation.blockCap ? { block_cap: operation.blockCap } : {}),
+                        ...(operation.tokenBudget ? { token_budget: operation.tokenBudget } : {}),
+                    }
+                    : {};
+                return await tool.impl(args, invocation.toolContext);
+            },
+        });
         async function applyRuntimePolicyMutationEffects() {
             try {
                 await requireMemory(memory).refreshAfterPolicyMutation();
@@ -1061,7 +1483,8 @@ export async function createExecutionRuntimeHostComposition(context, options = {
                 ? { sessionAccessAuthority: context.sessionAccessAuthority }
                 : {}),
         });
-        const workHubCoordination = new HostWorkHubCoordinationCoordinator({
+        workHubCoordination = new HostWorkHubCoordinationCoordinator({
+            routingModel: dependencies.workHubRoutingModel,
             configureModel: (input) => sessionCatalog.configureWorkHubModel(input),
             transitionConfiguration: (input) => requireSessionManager(manager).transitionSessionConfiguration(WORKHUB_COORDINATION_SESSION_ID, input),
             stateRoot: context.owner.capability.canonicalPath,
@@ -1556,7 +1979,35 @@ export async function createExecutionRuntimeHostComposition(context, options = {
             }),
             createRuntimeHostDomainModule({
                 id: 'client-capability',
-                handlers: [clientCapabilities.handlers],
+                handlers: [
+                    {
+                        ...clientCapabilities.handlers,
+                        'client.capability.replace': async (input, operationContext) => {
+                            const outcome = await clientCapabilities.handlers['client.capability.replace'](input, operationContext);
+                            if (outcome.ok && rootRecoveryCompleted && !draining) {
+                                // Registration completes outside the policy mutation gate before
+                                // recovery selects bindings or composes a backend. Serialize
+                                // reconnects and retain the task for the shutdown barrier.
+                                clientBoundRecovery = clientBoundRecovery.then(async () => {
+                                    if (draining)
+                                        return;
+                                    await coordinator.recover();
+                                    await messages.consumePendingAdmissions(recoverySessions
+                                        .filter((session) => session.toolProfile === 'workhub-coordination-v2')
+                                        .map((session) => session.id));
+                                });
+                                try {
+                                    await clientBoundRecovery;
+                                }
+                                catch (error) {
+                                    context.requestDrain();
+                                    throw error;
+                                }
+                            }
+                            return outcome;
+                        },
+                    },
+                ],
                 recovery: {
                     resources: async () => {
                         await recoverClientCapabilityOutcomes(stores.runtimeEventStore, recoverySessions.map((session) => session.id));
@@ -1630,6 +2081,7 @@ export async function createExecutionRuntimeHostComposition(context, options = {
                     async () => {
                         if (!rootRecoveryCompleted || poisonFailure)
                             return;
+                        await clientBoundRecovery.catch(() => undefined);
                         rootCloseTask ??= coordinator.close();
                         await rootCloseTask;
                     },
@@ -2028,6 +2480,24 @@ function requireGoal(coordinator) {
         throw new Error('Runtime Host Goal coordinator is not composed');
     return coordinator;
 }
+function pluginAttachmentArtifactKind(mimeType, name) {
+    const kind = attachmentKindFromMimeType(mimeType, name);
+    return kind === 'image' || kind === 'pdf' ? kind : 'file';
+}
+function pluginAttachmentRef(record) {
+    const mimeType = record.mimeType ?? 'application/octet-stream';
+    return {
+        kind: attachmentKindFromMimeType(mimeType, record.name),
+        name: record.name,
+        mimeType,
+        bytes: record.sizeBytes,
+        ref: {
+            kind: 'session_file',
+            sessionId: record.sessionId,
+            relativePath: record.relativePath,
+        },
+    };
+}
 /** Every run this Session has opened, named by the event spine that defines it. */
 async function sessionRunIds(runtimeEventStore, sessionId) {
     return (await runtimeEventStore.listSessionInvocations(sessionId)).map((invocation) => invocation.runId);