@capekai/core 1.0.0

package/src/runtime/host-dependencies.ts

@@ -0,0 +1,71 @@
+import type { Session } from '@capekai/types';
+import { getRuntimeHost } from './host';
+import type { RuntimeAudience, RuntimeDelivery, RuntimeEvent } from './events';
+
+type HostRuntimeAudience = Exclude<RuntimeAudience, { scope: 'origin' }>;
+
+export {
+  addMessageToQueue,
+  buildEffectiveContextHistory,
+  createMessage,
+  createPart,
+  createSession,
+  deleteMessage,
+  deleteQueuedMessage,
+  getAttachment,
+  getChildSessions,
+  getMessage,
+  getMessageWithParts,
+  getNextQueuedMessage,
+  getPart,
+  getPartsByMessage,
+  getPartsBySession,
+  getResponseFormat,
+  getSession,
+  getWorkspace,
+  getWorkspaceAutoApproveSeverity,
+  listLatestMessagesWithPartsPage,
+  listMessagesWithParts,
+  persistStreamingPartSnapshots,
+  syncMessageFts,
+  transitionToolToInterrupted,
+  transitionToolToRunningByCallId,
+  updateMessage,
+  updatePart,
+  updateSession,
+} from '../storage/runtime';
+
+export function emitRuntimeEvent(event: RuntimeEvent, audience: HostRuntimeAudience = { scope: 'global' }): void {
+  const delivery: RuntimeDelivery = { event, audience };
+  const host = getRuntimeHost().delivery;
+  host.observe?.(delivery);
+  host.emit(delivery);
+}
+
+export const emitSessionCreated = (session: Session): void =>
+  emitRuntimeEvent({ kind: 'session', action: 'created', session });
+export const emitSessionUpdated = (session: Session): void =>
+  emitRuntimeEvent({ kind: 'session', action: 'updated', session });
+export const emitToSession = (sessionId: string, event: RuntimeEvent): void =>
+  emitRuntimeEvent(event, { scope: 'session', sessionId });
+export const emitToController = (sessionId: string, event: RuntimeEvent): void =>
+  emitRuntimeEvent(event, { scope: 'controller', sessionId });
+export const emitToAskTargets = (
+  sessionId: string,
+  authority: Extract<RuntimeAudience, { scope: 'ask_targets' }>['authority'],
+  event: RuntimeEvent,
+): void => emitRuntimeEvent(event, { scope: 'ask_targets', sessionId, authority });
+export const emitTerminal = (message: Extract<RuntimeEvent, { kind: 'terminal' }>['message'], sessionId: string): void =>
+  emitRuntimeEvent({ kind: 'terminal', message, sessionId }, { scope: 'host' });
+
+export const isDefaultSessionTitle = (...args: Parameters<ReturnType<typeof getRuntimeHost>['titles']['isDefaultSessionTitle']>) =>
+  getRuntimeHost().titles.isDefaultSessionTitle(...args);
+export const hasManualSessionTitle = (...args: Parameters<ReturnType<typeof getRuntimeHost>['titles']['hasManualSessionTitle']>) =>
+  getRuntimeHost().titles.hasManualSessionTitle(...args);
+export const generateSessionTitle = (...args: Parameters<ReturnType<typeof getRuntimeHost>['titles']['generateSessionTitle']>) =>
+  getRuntimeHost().titles.generateSessionTitle(...args);
+export const getToolWorkspaceHost = (...args: Parameters<ReturnType<typeof getRuntimeHost>['workspace']['createToolWorkspaceHost']>) =>
+  getRuntimeHost().workspace.createToolWorkspaceHost(...args);
+export const isSandboxActive = (): boolean => getRuntimeHost().sandbox.isSandboxActive();
+
+export type { RuntimeEventSink, RuntimeEventSink as BroadcastFn } from './events';

package/src/runtime/host-guidance.ts

@@ -0,0 +1,22 @@
+import { MEMORY_GUIDANCE } from '../memory';
+import { AGENT_MEMORY_SKILLS_GUIDANCE } from '../plugins/legacy-system-message';
+import { SKILL_MANAGE_GUIDANCE } from '../skills';
+import { SESSION_SEARCH_GUIDANCE } from '../session-search';
+import { getRuntimeHost } from './host';
+
+export interface HostGuidance {
+  memory: string;
+  agentMemorySkills: string;
+  skillManage: string;
+  sessionSearch: string;
+}
+
+export function getHostGuidance(): HostGuidance {
+  const guidance = getRuntimeHost().guidance ?? {};
+  return {
+    memory: guidance.memory ?? MEMORY_GUIDANCE,
+    agentMemorySkills: guidance.agentMemorySkills ?? AGENT_MEMORY_SKILLS_GUIDANCE,
+    skillManage: guidance.skillManage ?? SKILL_MANAGE_GUIDANCE,
+    sessionSearch: guidance.sessionSearch ?? SESSION_SEARCH_GUIDANCE,
+  };
+}

package/src/runtime/host-layout.ts

@@ -0,0 +1,23 @@
+import os from 'node:os';
+import path from 'node:path';
+import { getRuntimeHost } from './host';
+
+export interface HostLayout {
+  workspaceMemoryDir(workspacePath: string): string;
+  workspaceSkillsDir(workspacePath: string): string;
+  agentSkillsDir(agentDir: string): string;
+  toolOutputTempRoot(): string;
+}
+
+function defaultLayout(): HostLayout {
+  return {
+    workspaceMemoryDir: (workspacePath) => path.join(workspacePath, '.capek'),
+    workspaceSkillsDir: (workspacePath) => path.join(workspacePath, '.agents', 'skills'),
+    agentSkillsDir: (agentDir) => path.join(agentDir, 'skills'),
+    toolOutputTempRoot: () => path.join(os.tmpdir(), 'capek'),
+  };
+}
+
+export function getHostLayout(): HostLayout {
+  return getRuntimeHost().layout ?? defaultLayout();
+}

package/src/runtime/host.ts

@@ -0,0 +1,129 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { HostLayout } from './host-layout';
+import type { Ask } from '@capekai/tool';
+import type {
+  AskRequestMessage, AskTimedOutMessage, AutoApproveSeverity, MessageWithParts, Session,
+} from '@capekai/types';
+import type { PermissionGrant, PermissionGrantOptions, PermissionResource } from '@capekai/tool';
+import type { WorkspaceCapabilityHost } from '../workspace/contracts';
+import type { RuntimeDelivery, RuntimeEvent } from './events';
+
+export type AskEventSink = (message: AskRequestMessage | AskTimedOutMessage) => void;
+export type RuntimeEventSink = (event: RuntimeEvent) => void;
+export type SessionEventSink = (session: Session) => void;
+export type AskBroadcastFn = AskEventSink;
+export type BroadcastFn = RuntimeEventSink;
+export type BroadcastSessionFn = SessionEventSink;
+export type PermissionRequestStatus = 'pending' | 'approved' | 'denied' | 'expired' | 'cancelled';
+
+export interface PendingAskRecord {
+  id: string;
+  requestId: string;
+  sessionId: string;
+  rootSessionId?: string;
+  originSessionId?: string;
+  workspaceId?: string;
+  toolCallId: string;
+  toolName: string;
+  ask: Ask;
+  status: PermissionRequestStatus;
+  isPermission: boolean;
+  expiresAt?: number;
+  resolvedAt?: number;
+  resolution?: unknown;
+  createdAt: number;
+}
+
+export interface MatchGrantParams {
+  workspaceId: string;
+  toolName: string;
+  resource: PermissionResource;
+  action?: string;
+  permissionKey: string;
+  rootSessionId?: string;
+}
+
+export interface CreateGrantParams {
+  workspaceId: string;
+  toolName: string;
+  resource: PermissionResource;
+  action?: string;
+  permissionKey: string;
+  grantOptions: PermissionGrantOptions;
+}
+
+export interface InteractionHost {
+  createPendingAsk(record: Omit<PendingAskRecord, 'id'>): Promise<string>;
+  removePendingAsk(id: string): Promise<void>;
+  removePendingAsksByToolCallId(toolCallId: string): Promise<void>;
+  getPermissionRequestByRequestId(requestId: string): Promise<PendingAskRecord | null>;
+  resolvePermissionRequestByRequestId(requestId: string, status: 'approved' | 'denied', resolution?: unknown): Promise<boolean>;
+  expirePermissionRequest(id: string): Promise<boolean>;
+  expireOldPermissionRequests(maxAgeMs: number): Promise<number>;
+  cancelPendingRequestsBySession(sessionId: string): Promise<number>;
+  listPendingAsksBySession(sessionId: string): Promise<PendingAskRecord[]>;
+  listPendingAsksByRootSession(rootSessionId: string): Promise<PendingAskRecord[]>;
+  listPendingRequestsByRootSession(rootSessionId: string): Promise<PendingAskRecord[]>;
+  matchGrant(params: MatchGrantParams): Promise<{ matched: boolean; grant: PermissionGrant | null }>;
+  createGrantFromOptions(params: CreateGrantParams): Promise<PermissionGrant | null>;
+  getSessionAutoApproveSeverity(sessionId: string): Promise<AutoApproveSeverity | undefined>;
+  getPermissionTimeoutMs(): number;
+  notifyPermissionRequired(requestId: string, rootSessionId: string): Promise<void>;
+}
+
+export interface DeliveryHost {
+  emit(delivery: RuntimeDelivery): void;
+  observe?(delivery: RuntimeDelivery): void;
+}
+
+export interface TitleHost {
+  isDefaultSessionTitle(title: string | null | undefined): boolean;
+  hasManualSessionTitle(metadata: Record<string, unknown> | null | undefined): boolean;
+  generateSessionTitle(messages: MessageWithParts[]): Promise<string | null>;
+}
+
+export interface WorkspaceCapabilityBindings {
+  createToolWorkspaceHost(options: {
+    workspaceId?: string;
+    workspacePath?: string;
+    additionalPaths?: string[];
+    sessionId: string;
+  }): WorkspaceCapabilityHost;
+}
+
+export interface SandboxBindings {
+  isSandboxActive(): boolean;
+}
+
+export interface RuntimeHost {
+  interaction: InteractionHost;
+  delivery: DeliveryHost;
+  titles: TitleHost;
+  workspace: WorkspaceCapabilityBindings;
+  sandbox: SandboxBindings;
+  /** Host-supplied filesystem layout policy. */
+  layout?: HostLayout;
+  guidance?: {
+    memory?: string;
+    agentMemorySkills?: string;
+    skillManage?: string;
+    sessionSearch?: string;
+  };
+}
+
+let host: RuntimeHost | null = null;
+const scopedHost = new AsyncLocalStorage<RuntimeHost>();
+
+export function configureRuntimeHost(value: RuntimeHost): void {
+  host = value;
+}
+
+export function withRuntimeHost<T>(value: RuntimeHost, callback: () => T): T {
+  return scopedHost.run(value, callback);
+}
+
+export function getRuntimeHost(): RuntimeHost {
+  const active = scopedHost.getStore() ?? host;
+  if (!active) throw new Error('Runtime host has not been configured');
+  return active;
+}

package/src/runtime/standalone-host.ts

@@ -0,0 +1,118 @@
+import { join } from 'node:path';
+import type { AutoApproveSeverity } from '@capekai/types';
+import { PermissionGrant } from '@capekai/tool';
+import type {
+  PendingAskRecord,
+  RuntimeHost,
+} from './host';
+
+interface StandaloneHostOptions {
+  workspace: string;
+  sandboxActive: boolean;
+  tempRoot: string;
+}
+
+/** The reference headless `RuntimeHost`. In-memory pending-ask bookkeeping,
+ * no grant persistence (every permission ask reaches the host every time),
+ * no auto-approve, no-op delivery/titles, process env for tool workspaces.
+ * Copy this as the starting point for your own host and replace the
+ * behavior you care about. */
+export function createStandaloneHost(options: StandaloneHostOptions): RuntimeHost {
+  const pending = new Map<string, PendingAskRecord>();
+  const recordIdByRequest = new Map<string, string>();
+  let sequence = 0;
+
+  const records = (): PendingAskRecord[] => [...pending.values()];
+  const byRequest = (requestId: string): PendingAskRecord | null => {
+    const id = recordIdByRequest.get(requestId);
+    return id ? pending.get(id) ?? null : null;
+  };
+
+  return {
+    interaction: {
+      async createPendingAsk(record) {
+        const id = `standalone-ask-${++sequence}`;
+        pending.set(id, { ...record, id });
+        recordIdByRequest.set(record.requestId, id);
+        return id;
+      },
+      async removePendingAsk(id) {
+        const record = pending.get(id);
+        if (record) recordIdByRequest.delete(record.requestId);
+        pending.delete(id);
+      },
+      async removePendingAsksByToolCallId(toolCallId) {
+        for (const record of records()) {
+          if (record.toolCallId === toolCallId) {
+            pending.delete(record.id);
+            recordIdByRequest.delete(record.requestId);
+          }
+        }
+      },
+      getPermissionRequestByRequestId: async (requestId) => byRequest(requestId),
+      async resolvePermissionRequestByRequestId(requestId, status, resolution) {
+        const record = byRequest(requestId);
+        if (!record || record.status !== 'pending') return false;
+        pending.set(record.id, { ...record, status, resolution, resolvedAt: Date.now() });
+        return true;
+      },
+      async expirePermissionRequest(id) {
+        const record = pending.get(id);
+        if (!record || record.status !== 'pending') return false;
+        pending.set(id, { ...record, status: 'expired', resolvedAt: Date.now() });
+        return true;
+      },
+      async expireOldPermissionRequests(maxAgeMs) {
+        const cutoff = Date.now() - maxAgeMs;
+        let count = 0;
+        for (const record of records()) {
+          if (record.status === 'pending' && record.createdAt < cutoff) {
+            pending.set(record.id, { ...record, status: 'expired', resolvedAt: Date.now() });
+            count += 1;
+          }
+        }
+        return count;
+      },
+      async cancelPendingRequestsBySession(sessionId) {
+        let count = 0;
+        for (const record of records()) {
+          if (record.sessionId === sessionId && record.status === 'pending') {
+            pending.set(record.id, { ...record, status: 'cancelled', resolvedAt: Date.now() });
+            count += 1;
+          }
+        }
+        return count;
+      },
+      listPendingAsksBySession: async (sessionId) => records().filter((record) => record.sessionId === sessionId && record.status === 'pending'),
+      listPendingAsksByRootSession: async (rootSessionId) => records().filter((record) => record.rootSessionId === rootSessionId && record.status === 'pending'),
+      listPendingRequestsByRootSession: async (rootSessionId) => records().filter((record) => record.rootSessionId === rootSessionId && record.status === 'pending'),
+      matchGrant: async () => ({ matched: false, grant: null }),
+      createGrantFromOptions: async () => null as PermissionGrant | null,
+      getSessionAutoApproveSeverity: async () => undefined as AutoApproveSeverity | undefined,
+      getPermissionTimeoutMs: () => 30 * 60 * 1000,
+      notifyPermissionRequired: async () => {},
+    },
+    delivery: {
+      emit: () => {},
+    },
+    titles: {
+      isDefaultSessionTitle: () => true,
+      hasManualSessionTitle: () => false,
+      generateSessionTitle: async () => null,
+    },
+    workspace: {
+      createToolWorkspaceHost({ workspacePath, additionalPaths, sessionId }) {
+        return {
+          root: workspacePath ?? options.workspace,
+          additionalRoots: additionalPaths,
+          allowedRoots: [],
+          tempDir: join(options.tempRoot, sessionId),
+          getEnvironmentValue: (key) => process.env[key],
+        };
+      },
+    },
+    sandbox: {
+      isSandboxActive: () => options.sandboxActive,
+    },
+  };
+}

package/src/sandbox/controller.ts

@@ -0,0 +1,204 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type {
+  AutoResponderRule,
+  LlmCallContext,
+  SandboxControlEvent,
+  SandboxHistoryEntry,
+  SandboxResponse,
+} from './types';
+
+interface PendingCall {
+  context: LlmCallContext;
+  resolve: (response: SandboxResponse) => void;
+  reject: (reason: unknown) => void;
+}
+
+interface InternalAutoResponderRule extends AutoResponderRule {
+  uses: number;
+}
+
+function cloneResponse(response: SandboxResponse): SandboxResponse {
+  if (response.type === 'multi-tool-call') {
+    return {
+      ...response,
+      calls: response.calls.map((call) => ({ ...call, args: { ...call.args } })),
+    };
+  }
+  if (response.type === 'tool-call') {
+    return { ...response, args: { ...response.args } };
+  }
+  return { ...response };
+}
+
+function hasToolResults(context: LlmCallContext): boolean {
+  return context.messages.some((message) => Array.isArray(message.content)
+    && message.content.some((part) => part !== null
+      && typeof part === 'object'
+      && (part as { type?: unknown }).type === 'tool-result'));
+}
+
+function matchesScalar<T extends string | number>(value: T, matcher: T | T[] | undefined): boolean {
+  if (matcher === undefined) return true;
+  return Array.isArray(matcher) ? matcher.includes(value) : matcher === value;
+}
+
+export class SandboxController {
+  private pendingCalls = new Map<string, PendingCall>();
+  private history: SandboxHistoryEntry[] = [];
+  private autoResponderRules: InternalAutoResponderRule[] = [];
+  private broadcastEvent: ((event: SandboxControlEvent) => void) | null = null;
+
+  constructor(initialRules: AutoResponderRule[] = []) {
+    this.setAutoResponderRules(initialRules);
+  }
+
+  async waitForResponse(context: LlmCallContext, abortSignal?: AbortSignal): Promise<SandboxResponse> {
+    const historyEntry: SandboxHistoryEntry = {
+      callId: context.callId,
+      context,
+      response: null,
+      respondedAt: null,
+      completedAt: null,
+    };
+    this.history.push(historyEntry);
+
+    const rule = this.findMatchingRule(context);
+    if (rule) {
+      const response = cloneResponse(rule.response);
+      historyEntry.response = response;
+      historyEntry.respondedAt = Date.now();
+      this.broadcastHistory();
+      return response;
+    }
+
+    this.broadcast({ type: 'sandbox.call_waiting', context });
+    this.broadcastHistory();
+
+    return new Promise<SandboxResponse>((resolve, reject) => {
+      this.pendingCalls.set(context.callId, { context, resolve, reject });
+      if (!abortSignal) return;
+      if (abortSignal.aborted) {
+        this.pendingCalls.delete(context.callId);
+        reject(new DOMException('The operation was aborted.', 'AbortError'));
+        return;
+      }
+      abortSignal.addEventListener('abort', () => {
+        if (this.pendingCalls.has(context.callId)) {
+          this.pendingCalls.delete(context.callId);
+          reject(new DOMException('The operation was aborted.', 'AbortError'));
+        }
+      }, { once: true });
+    });
+  }
+
+  respond(callId: string, response: SandboxResponse): void {
+    const pending = this.pendingCalls.get(callId);
+    if (!pending) throw new Error(`No pending call with id: ${callId}`);
+    this.pendingCalls.delete(callId);
+    const entry = this.history.find((candidate) => candidate.callId === callId);
+    if (entry) {
+      entry.response = cloneResponse(response);
+      entry.respondedAt = Date.now();
+    }
+    this.broadcastHistory();
+    pending.resolve(response);
+  }
+
+  rejectPendingCall(callId: string, reason: unknown): void {
+    const pending = this.pendingCalls.get(callId);
+    if (!pending) return;
+    this.pendingCalls.delete(callId);
+    pending.reject(reason);
+  }
+
+  rejectAllPendingForSession(sessionId: string): string[] {
+    const rejectedCallIds: string[] = [];
+    for (const [callId, pending] of this.pendingCalls) {
+      if (pending.context.sessionId !== sessionId) continue;
+      this.pendingCalls.delete(callId);
+      pending.reject(new DOMException('The operation was aborted.', 'AbortError'));
+      rejectedCallIds.push(callId);
+    }
+    return rejectedCallIds;
+  }
+
+  complete(callId: string): void {
+    const entry = this.history.find((candidate) => candidate.callId === callId);
+    if (entry) entry.completedAt = Date.now();
+    this.broadcast({ type: 'sandbox.call_completed', callId });
+    this.broadcastHistory();
+  }
+
+  getPendingCalls(): LlmCallContext[] {
+    return Array.from(this.pendingCalls.values()).map((pending) => pending.context);
+  }
+
+  getPendingCall(callId: string): LlmCallContext | undefined {
+    return this.pendingCalls.get(callId)?.context;
+  }
+
+  getHistory(): SandboxHistoryEntry[] {
+    return [...this.history];
+  }
+
+  clearHistory(): void {
+    this.history = [];
+    this.broadcastHistory();
+  }
+
+  getAutoResponderRules(): AutoResponderRule[] {
+    return this.autoResponderRules.map(({ uses: _uses, ...rule }) => rule);
+  }
+
+  setAutoResponderRules(rules: AutoResponderRule[]): void {
+    this.autoResponderRules = rules.map((rule) => ({ ...rule, response: cloneResponse(rule.response), uses: 0 }));
+  }
+
+  setBroadcast(fn: ((event: SandboxControlEvent) => void) | null): void {
+    this.broadcastEvent = fn;
+  }
+
+  reset(): void {
+    for (const pending of this.pendingCalls.values()) pending.reject(new Error('Sandbox controller reset'));
+    this.pendingCalls = new Map<string, PendingCall>();
+    this.history = [];
+    this.autoResponderRules = [];
+    this.broadcastEvent = null;
+  }
+
+  private findMatchingRule(context: LlmCallContext): InternalAutoResponderRule | null {
+    for (const rule of this.autoResponderRules) {
+      if (!matchesScalar(context.mode, rule.match.mode)
+        || !matchesScalar(context.depth, rule.match.depth)
+        || !matchesScalar(context.sessionId, rule.match.sessionId)
+        || (rule.match.hasToolResults !== undefined && rule.match.hasToolResults !== hasToolResults(context))) {
+        continue;
+      }
+      rule.uses += 1;
+      if (rule.maxUses !== undefined && rule.uses >= rule.maxUses) {
+        this.autoResponderRules = this.autoResponderRules.filter((candidate) => candidate !== rule);
+      }
+      return rule;
+    }
+    return null;
+  }
+
+  private broadcast(event: SandboxControlEvent): void {
+    this.broadcastEvent?.(event);
+  }
+
+  private broadcastHistory(): void {
+    this.broadcast({ type: 'sandbox.history', entries: this.getHistory() });
+  }
+}
+
+export const sandboxController = new SandboxController();
+const scopedSandboxController = new AsyncLocalStorage<SandboxController>();
+
+export function getSandboxController(): SandboxController {
+  return scopedSandboxController.getStore() ?? sandboxController;
+}
+
+export function withSandboxController<T>(controller: SandboxController, callback: () => T): T {
+  return scopedSandboxController.run(controller, callback);
+}