@capekai/core 1.0.0

package/src/plugins/subagent-domain.ts

@@ -0,0 +1,287 @@
+import type { Preconfig } from '@capekai/types'
+import type { ToolDefinition } from '@capekai/tool';
+import { validateContextAssemblyData, type ContextAssemblyData } from '../context/assembler';
+import { serviceKey } from '../kernel/service-key';
+import type {
+  CapekPlugin,
+  ContextSectionContribution,
+  PluginContext,
+  ToolDefinition as KernelToolDefinition,
+} from '../kernel/types';
+import {
+  DOMAIN_TOOL_PAYLOAD_FIELD,
+  registerDomainToolFallback,
+  type DomainToolPayload,
+} from '../runtime/domain-tool-source';
+import type { RuntimeDelivery, RuntimeEvent } from '../runtime/events';
+import type { BroadcastFn, RuntimeHost } from '../runtime/host';
+import type { StorageBundle } from '../storage/contracts';
+import { executeChildSession } from '../subagent/child-session';
+import { selfDelegationGuidance } from '../subagent/guidance';
+import {
+  resolveEffectiveSubagentTargets,
+  type ResolveSubagentTargetsOptions,
+} from '../subagent/policy';
+import {
+  buildTaskToolDefinition,
+  canSpawnSubagent,
+  canSpawnSubagentWithDeps,
+  executeSubagent,
+  executeSubagentWithDeps,
+  getSubagentToolDefinition,
+  type GetSubagentToolDefinitionOptions,
+  type SubagentInput,
+  type SubagentOutput,
+  type SubagentServiceBroadcasts,
+  type SubagentServiceDeps,
+  type SubagentServiceSessionAccess,
+} from '../subagent/task-tool';
+import { capekContextSourcesKey, capekRuntimeHostKey, capekStorageKey } from './service-keys';
+
+/**
+ * C5 subagent domain plugin. Owns the agent-scoped subagent service (depth
+ * and ancestry policy over the captured storage and preconfig sources), the
+ * `task` tool contribution through the generic contributed-domain-tool seam,
+ * and the `self-delegation` context section. Composed payloads never read
+ * module-level globals; the unscoped fallback keeps the pre-C5
+ * execute-time module accessors and is installed explicitly, never at
+ * module load.
+ */
+
+export const CURRENT_SUBAGENT_DOMAIN_PLUGIN_ID = 'current.subagent-domain';
+export const SUBAGENT_TOOL_CONTRIBUTION_ID = 'subagent.task';
+/** Before session-search (700) and scheduler (750) so the contributed tool
+ * order keeps `task` ahead of the workspace-gated domain tools, matching
+ * the pre-C5 buildAiSdkTools phase-1 placement. */
+export const SUBAGENT_TOOL_CONTRIBUTION_ORDER = 650;
+export const SELF_DELEGATION_SECTION_ID = 'self-delegation';
+
+export interface SubagentDomainService {
+  readonly tools: readonly DomainToolPayload[];
+  /** Depth gate shared by the task tool payload. */
+  canSpawnSubagent(sessionId: string): Promise<boolean>;
+  resolveTargets(options: ResolveSubagentTargetsOptions): Promise<Preconfig[]>;
+  /** Composed leaf execution for other C5 domains (workflow): runs the task
+   * execution path over this domain's scope-captured deps, never module
+   * globals. */
+  execute(input: SubagentInput): Promise<SubagentOutput>;
+  /** Scope-captured subagent preconfig listing for other C5 domains
+   * (workflow decomposition). */
+  listSubagents(): Promise<Preconfig[]>;
+  /** Whether the current session may delegate to a fresh instance of its own
+   * preconfig: task tool visible + allowSelfAsSubagent + the resolved target
+   * list contains the current preconfig. Mirrors the pre-C5 agent.ts
+   * computation over the same domain policy. */
+  selfDelegationAvailable(
+    sessionId: string,
+    preconfigId: string,
+    allowSelfAsSubagent: boolean,
+  ): Promise<boolean>;
+  guidance(preconfigId: string): string;
+}
+
+export const capekSubagentDomainKey = serviceKey<SubagentDomainService>(
+  'capek.subagent-domain',
+  'agent',
+);
+
+function deliver(host: RuntimeHost, delivery: RuntimeDelivery): void {
+  host.delivery.observe?.(delivery);
+  host.delivery.emit(delivery);
+}
+
+/** Runtime-host delivery projection shared by the C5 domain plugins
+ * (subagent, workflow) that route leaf events through the captured host. */
+export function broadcastsFromHost(host: RuntimeHost): SubagentServiceBroadcasts {
+  return {
+    event: (event) => deliver(host, { event, audience: { scope: 'global' } }),
+    sessionCreated: (session) =>
+      deliver(host, { event: { kind: 'session', action: 'created', session }, audience: { scope: 'global' } }),
+    sessionUpdated: (session) =>
+      deliver(host, { event: { kind: 'session', action: 'updated', session }, audience: { scope: 'global' } }),
+    toSession: (sessionId: string, event: RuntimeEvent) =>
+      deliver(host, { event, audience: { scope: 'session', sessionId } }),
+  };
+}
+
+interface TaskPayloadDeps {
+  canSpawn: (sessionId: string) => boolean | Promise<boolean>;
+  resolveDefinition: (
+    options: GetSubagentToolDefinitionOptions,
+  ) => Promise<ToolDefinition | null>;
+  execute: (input: SubagentInput) => Promise<Record<string, unknown>>;
+}
+
+function taskPayload(deps: TaskPayloadDeps): DomainToolPayload {
+  const placeholder = buildTaskToolDefinition([]);
+  return {
+    name: placeholder.name,
+    description: placeholder.description,
+    inputSchema: placeholder.inputSchema,
+    display: { summary: '{description}' },
+    visualize: (_input, result) => {
+      const taskId = typeof result.task_id === 'string' ? result.task_id : '';
+      const text = typeof result.result === 'string' ? result.result : '';
+      return {
+        type: 'none',
+        badge: taskId ? 'session ready' : undefined,
+        message: text.split('\n').filter((line) => line && !line.startsWith('task_id:'))
+          .join('\n').replace(/<\/?task_result>/g, '').replace(/<\/?structured_result>/g, '').trim().slice(0, 200) || 'Subagent completed',
+      };
+    },
+    isEnabled: async (workspaceId, sessionId) =>
+      typeof sessionId === 'string' && await deps.canSpawn(sessionId),
+    resolveDefinition: async (sessionId, options) => {
+      const definition = await deps.resolveDefinition({
+        sessionId,
+        canSpawnSubagents: options?.canSpawnSubagents as boolean | string[] | null | undefined,
+        allowSelfAsSubagent: options?.allowSelfAsSubagent as boolean | undefined,
+      });
+      if (!definition) return null;
+      return {
+        description: definition.description,
+        inputSchema: definition.inputSchema,
+      };
+    },
+    execute: async (input, context) => {
+      const subagentInput: SubagentInput = {
+        description: input.description as string,
+        prompt: input.prompt as string,
+        subagent_type: input.subagent_type as string,
+        task_id: input.task_id as string | undefined,
+        sessionId: context.sessionId,
+        workspaceId: typeof context.workspaceId === 'string' ? context.workspaceId : undefined,
+        workspacePath: typeof context.workspacePath === 'string' ? context.workspacePath : undefined,
+        abortSignal: context.abortSignal as AbortSignal | undefined,
+        onSessionCreated: context.onSessionCreated as ((childSessionId: string) => void | Promise<void>) | undefined,
+        allowedSubagentIds: context.allowedSubagentIds as string[] | undefined,
+        broadcast: context.broadcast as BroadcastFn | undefined,
+        ...(input.outputSchema ? { outputSchema: input.outputSchema as Record<string, unknown> } : {}),
+      };
+      return deps.execute(subagentInput);
+    },
+  };
+}
+
+/** Unscoped compatibility payload: keeps the pre-C5 execute-time module
+ * accessors. Installed through `installTaskToolFallback`, never at module
+ * load. */
+export function createTaskToolFallbackPayload(): DomainToolPayload {
+  return taskPayload({
+    canSpawn: (sessionId) => canSpawnSubagent(sessionId),
+    resolveDefinition: (options) => getSubagentToolDefinition(options),
+    execute: async (input) => executeSubagent(input) as unknown as Record<string, unknown>,
+  });
+}
+
+/** Explicitly installs the unscoped legacy fallback. Called by the Jean2
+ * compatibility bindings installation (server bootstrap) and by focused
+ * tests; no module-load registration exists. */
+export function installTaskToolFallback(): void {
+  registerDomainToolFallback('task', createTaskToolFallbackPayload());
+}
+
+type GuidanceSectionContribution = ContextSectionContribution<ContextAssemblyData>;
+
+export function subagentDomainPlugin(id: string): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekSubagentDomainKey],
+    requires: [capekStorageKey, capekContextSourcesKey, capekRuntimeHostKey],
+    setup(context: PluginContext) {
+      const storage: StorageBundle = context.require(capekStorageKey);
+      const contextSources = context.require(capekContextSourcesKey);
+      const host: RuntimeHost = context.require(capekRuntimeHostKey);
+      const preconfigSource = contextSources.preconfigs;
+      const getPreconfigOrAgentScoped = (preconfigId: string): Promise<Preconfig | null> =>
+        preconfigSource ? preconfigSource.getForAgent(preconfigId) : Promise.resolve(null);
+      const listSubagentPreconfigsScoped = (): Promise<Preconfig[]> =>
+        preconfigSource ? preconfigSource.listSubagents() : Promise.resolve([]);
+
+      const sessionAccess: SubagentServiceSessionAccess = {
+        getSession: async (sessionId) => storage.conversation.getSession(sessionId),
+        createSession: async (session) => storage.conversation.createSession(session),
+        updateSession: async (sessionId, updates) => storage.conversation.updateSession(sessionId, updates),
+        getWorkspaceAutoApproveSeverity: async (workspaceId) => storage.workspaces.getAutoApproveSeverity(workspaceId),
+      };
+
+      const serviceDeps: SubagentServiceDeps = {
+        sessionAccess,
+        preconfigs: {
+          getPreconfigOrAgent: getPreconfigOrAgentScoped,
+          listSubagentPreconfigs: listSubagentPreconfigsScoped,
+        },
+        broadcasts: broadcastsFromHost(host),
+        executeChild: executeChildSession,
+      };
+
+      const service: SubagentDomainService = {
+        tools: [
+          taskPayload({
+            canSpawn: async (sessionId) => canSpawnSubagentWithDeps(sessionId, sessionAccess.getSession),
+            resolveDefinition: async (options) => {
+              // The composed path resolves targets through the scope-captured
+              // storage and preconfig sources; it never reads module globals.
+              const deps = {
+                getSession: sessionAccess.getSession,
+                listPreconfigs: listSubagentPreconfigsScoped,
+              };
+              const maximumDepthReached = !(await canSpawnSubagentWithDeps(options.sessionId, deps.getSession));
+              return resolveEffectiveSubagentTargets({
+                ...options,
+                maximumDepthReached,
+              }, deps).then((targets) =>
+                targets.length === 0 ? null : buildTaskToolDefinition(targets));
+            },
+            execute: (input) => executeSubagentWithDeps(input, serviceDeps) as unknown as Promise<Record<string, unknown>>,
+          }),
+        ],
+        canSpawnSubagent: async (sessionId) => canSpawnSubagentWithDeps(sessionId, sessionAccess.getSession),
+        execute: (input) => executeSubagentWithDeps(input, serviceDeps),
+        listSubagents: listSubagentPreconfigsScoped,
+        resolveTargets: (options) => resolveEffectiveSubagentTargets(options, {
+          getSession: sessionAccess.getSession,
+          listPreconfigs: listSubagentPreconfigsScoped,
+        }),
+        selfDelegationAvailable: async (sessionId, preconfigId, allowSelfAsSubagent) =>
+          resolveEffectiveSubagentTargets({
+            sessionId,
+            canSpawnSubagents: true,
+            allowSelfAsSubagent,
+            maximumDepthReached: !(await canSpawnSubagentWithDeps(sessionId, sessionAccess.getSession)),
+          }, {
+            getSession: sessionAccess.getSession,
+            listPreconfigs: listSubagentPreconfigsScoped,
+          }).then((targets) =>
+            allowSelfAsSubagent === true && targets.some((candidate) => candidate.id === preconfigId)),
+        guidance: selfDelegationGuidance,
+      };
+
+      const guidance: GuidanceSectionContribution = {
+        id: SELF_DELEGATION_SECTION_ID,
+        phase: 'identity',
+        order: 50,
+        provide: (build) => {
+          const data = validateContextAssemblyData(build.data);
+          return data.selfDelegationAvailable ? service.guidance(data.preconfig.id) : null;
+        },
+      };
+
+      context.provide(capekSubagentDomainKey, service);
+      context.contributeTool({
+        id: SUBAGENT_TOOL_CONTRIBUTION_ID,
+        order: SUBAGENT_TOOL_CONTRIBUTION_ORDER,
+        definition: {
+          name: service.tools[0].name,
+          description: service.tools[0].description,
+          inputSchema: service.tools[0].inputSchema,
+          timeout: 300000,
+          [DOMAIN_TOOL_PAYLOAD_FIELD]: service.tools[0],
+        } as KernelToolDefinition,
+        requiredCapabilities: [capekSubagentDomainKey],
+      });
+      context.contributeContext(guidance);
+    },
+  };
+}

package/src/plugins/tool-catalog.ts

@@ -0,0 +1,78 @@
+/**
+ * Contributed tool catalog.
+ *
+ * Joins the effective tool contributions of a scope with the payloads
+ * carried on those contributions (`ToolContribution.payload`). The resolver
+ * re-attaches each contributed definition to its executor and install path
+ * by identity, in the deterministic kernel tool order.
+ */
+
+import type { LoadedTool } from '@capekai/tool';
+import type { CapekPlugin, EffectiveTool, PluginContext, ServiceKey } from '../kernel/types';
+import type { ToolRegistryResolver } from '../tools/registry';
+import { capekToolResolverKey } from './service-keys';
+
+/** The narrow surface a contributed resolver reads: effective tools plus
+ * optional service resolution. `ScopeHandle` and `PluginContext` both
+ * satisfy it. */
+export interface ContributedToolScope {
+  listTools(): readonly EffectiveTool[];
+  optional<T>(key: ServiceKey<T>): T | undefined;
+}
+
+function isLoadedToolPayload(value: unknown): value is LoadedTool {
+  if (typeof value !== 'object' || value === null) return false;
+  const candidate = value as { definition?: unknown; execute?: unknown };
+  return typeof candidate.definition === 'object' && candidate.definition !== null
+    && typeof candidate.execute === 'function';
+}
+
+/** Builds a `ToolRegistryResolver` from the scope's effective visible tool
+ * contributions carrying payloads. Hidden tools are omitted, exactly like
+ * the kernel's effective visibility decision. Order follows the
+ * deterministic kernel tool order. The payload snapshot is taken lazily on
+ * first use, so plugin activation order (the resolver plugin id may sort
+ * before payload-contributing plugins) cannot drop contributions. */
+export function createContributedToolResolver(
+  scope: ContributedToolScope,
+): ToolRegistryResolver {
+  let loaded: LoadedTool[] | null = null;
+  const byName = new Map<string, LoadedTool>();
+  const ensureSnapshot = (): void => {
+    if (loaded !== null) return;
+    const collected: LoadedTool[] = [];
+    for (const tool of scope.listTools()) {
+      if (!tool.visible) continue;
+      const payload = tool.payload;
+      if (isLoadedToolPayload(payload) && payload.definition.name === tool.definition.name) {
+        collected.push(payload);
+        byName.set(payload.definition.name, payload);
+      }
+    }
+    loaded = collected;
+  };
+  return {
+    get(name: string): LoadedTool | null {
+      ensureSnapshot();
+      return byName.get(name) ?? null;
+    },
+    list(): LoadedTool[] {
+      ensureSnapshot();
+      return [...loaded!];
+    },
+  };
+}
+
+/** Agent plugin that provides `capek.tool-resolver` with a resolver built
+ * from this scope's effective contributed tool payloads. The resolver stays
+ * bound to the owning scope. */
+export function contributedToolResolverPlugin(id: string): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekToolResolverKey],
+    setup(context: PluginContext) {
+      context.provide(capekToolResolverKey, createContributedToolResolver(context));
+    },
+  };
+}

package/src/plugins/tool-output-policy.ts

@@ -0,0 +1,52 @@
+import { getHostLayout } from '../runtime/host-layout';
+import type { CapekPlugin, PluginContext, ToolDefinition as KernelToolDefinition } from '../kernel/types';
+import {
+  createToolOutputService,
+  retrieveToolOutputStandardTool,
+  type ToolOutputPolicyOptions,
+} from '../tool-output/policy';
+import { capekToolOutputPolicyKey } from './service-keys';
+
+/**
+ * C6 provider for the agent-scoped tool-output policy service
+ * (`capek.tool-output-policy`). The bounding thresholds and legacy
+ * truncation constants translate into provider options here, at
+ * composition: there is no current environment source for them, so the
+ * exact pre-C6 constants freeze into the service options (the same
+ * documented pattern as the generic ask timeout in C6 step 3). The page
+ * limits (10k default, 20k max) are mandatory storage invariants and are
+ * NOT options. The default provider reproduces the exact envelope,
+ * fallback, retrieval, wrap, and truncation behavior; the strict ID
+ * validation and session-scoped retrieval invariants stay in the storage
+ * layer.
+ */
+export function toolOutputPolicyPlugin(id: string, tempRoot?: string): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekToolOutputPolicyKey],
+    setup(context: PluginContext) {
+      const options: ToolOutputPolicyOptions = {
+        thresholdChars: 50_000,
+        previewChars: 10_000,
+        retrievalToolName: 'retrieve-tool-output',
+        truncationMaxChars: 50_000,
+        truncationPreviewChars: 10_000,
+        truncationTempDir: tempRoot ?? getHostLayout().toolOutputTempRoot(),
+      };
+      context.provide(
+        capekToolOutputPolicyKey,
+        createToolOutputService({ id, options }),
+      );
+      // The retrieval tool is the tool-output capability's own contribution:
+      // it enters the effective catalog through the service it depends on.
+      context.contributeTool({
+        id: 'tool-output.retrieve-tool-output',
+        order: 600,
+        definition: retrieveToolOutputStandardTool.definition as KernelToolDefinition,
+        payload: retrieveToolOutputStandardTool,
+        requiredCapabilities: [capekToolOutputPolicyKey],
+      });
+    },
+  };
+}

package/src/plugins/value-plugins.ts

@@ -0,0 +1,150 @@
+/**
+ * Value-bound provider plugin factories. Each factory produces one plugin
+ * that provides one C2 service key with the exact supplied value; the plugin
+ * declares the key in `provides` so kernel validation and diagnostics see the
+ * real ownership. Plugins carry no disposable resources: disposal never
+ * closes storage, controllers, or hosts.
+ */
+
+import type { CapekPlugin, ServiceKey } from '../kernel/types';
+import type { RuntimeConfiguration } from '../configuration/contracts';
+import type { ContextSources } from '../context/sources';
+import {
+  connectProvider,
+  createModelForProvider,
+  disconnectProvider,
+  getConnectableProviders,
+  getProvider,
+  getProviderStatus,
+  registerProvider,
+} from '../providers/registry';
+import type { ConnectableProvider } from '../providers/types';
+import type { RuntimeHost } from '../runtime/host';
+import type { SandboxController } from '../sandbox/controller';
+import type { SchedulerHost } from '../scheduler/host';
+import type { SessionSearchHost } from '../session-search/host';
+import type { StorageBundle } from '../storage/contracts';
+import {
+  clearCache,
+  configureToolsPath,
+  getTool,
+  listTools,
+  scanTools,
+  stopWatching,
+  watchTools,
+  type ToolRegistryResolver,
+} from '../tools/registry';
+import type { WorkspaceToolDiscovery } from '../tools/tool-source';
+import {
+  capekContextSourcesKey,
+  capekInstalledToolRegistryKey,
+  capekProviderOverridesKey,
+  capekProviderRegistryKey,
+  capekRuntimeConfigurationKey,
+  capekRuntimeHostKey,
+  capekSandboxControllerKey,
+  capekSchedulerHostKey,
+  capekSessionSearchHostKey,
+  capekStorageKey,
+  capekToolResolverKey,
+  capekWorkspaceToolDiscoveryKey,
+  type InstalledToolRegistryContract,
+  type ProviderRegistryContract,
+} from './service-keys';
+
+function valuePlugin<T>(id: string, key: ServiceKey<T>, value: T): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: key.scope,
+    provides: [key],
+    setup(context) {
+      context.provide(key, value);
+    },
+  };
+}
+
+export function storageValuePlugin(id: string, storage: StorageBundle): CapekPlugin<unknown> {
+  return valuePlugin(id, capekStorageKey, storage);
+}
+
+export function runtimeConfigurationValuePlugin(
+  id: string,
+  configuration: RuntimeConfiguration,
+): CapekPlugin<unknown> {
+  return valuePlugin(id, capekRuntimeConfigurationKey, configuration);
+}
+
+export function runtimeHostValuePlugin(id: string, host: RuntimeHost): CapekPlugin<unknown> {
+  return valuePlugin(id, capekRuntimeHostKey, host);
+}
+
+export function contextSourcesValuePlugin(
+  id: string,
+  sources: Partial<ContextSources>,
+): CapekPlugin<unknown> {
+  return valuePlugin(id, capekContextSourcesKey, sources);
+}
+
+export function workspaceToolDiscoveryValuePlugin(
+  id: string,
+  discovery: WorkspaceToolDiscovery,
+): CapekPlugin<unknown> {
+  return valuePlugin(id, capekWorkspaceToolDiscoveryKey, discovery);
+}
+
+export function toolResolverValuePlugin(id: string, resolver: ToolRegistryResolver): CapekPlugin<unknown> {
+  return valuePlugin(id, capekToolResolverKey, resolver);
+}
+
+export function sandboxControllerValuePlugin(
+  id: string,
+  controller: SandboxController,
+): CapekPlugin<unknown> {
+  return valuePlugin(id, capekSandboxControllerKey, controller);
+}
+
+export function providerOverridesValuePlugin(
+  id: string,
+  overrides: ReadonlyMap<string, ConnectableProvider>,
+): CapekPlugin<unknown> {
+  return valuePlugin(id, capekProviderOverridesKey, overrides);
+}
+
+/** Process-scope registry provider. Delegates to the current module
+ * functions, which read the seeded per-agent overrides exactly like the
+ * runtime does today. */
+export function providerRegistryValuePlugin(id: string): CapekPlugin<unknown> {
+  const registry: ProviderRegistryContract = {
+    registerProvider,
+    getProvider,
+    getConnectableProviders,
+    getProviderStatus,
+    connectProvider,
+    disconnectProvider,
+    createModelForProvider,
+  };
+  return valuePlugin(id, capekProviderRegistryKey, registry);
+}
+
+/** Process-scope installed tool registry provider. Delegates to the current
+ * module functions, which read the seeded resolver first. */
+export function installedToolRegistryValuePlugin(id: string): CapekPlugin<unknown> {
+  const registry: InstalledToolRegistryContract = {
+    getTool,
+    listTools,
+    scanTools,
+    watchTools,
+    stopWatching,
+    clearCache,
+    configureToolsPath,
+  };
+  return valuePlugin(id, capekInstalledToolRegistryKey, registry);
+}
+
+export function sessionSearchHostValuePlugin(id: string, host: SessionSearchHost): CapekPlugin<unknown> {
+  return valuePlugin(id, capekSessionSearchHostKey, host);
+}
+
+export function schedulerHostValuePlugin(id: string, host: SchedulerHost): CapekPlugin<unknown> {
+  return valuePlugin(id, capekSchedulerHostKey, host);
+}