@capekai/core 1.0.0

package/src/kernel/service-key.ts

@@ -0,0 +1,19 @@
+/**
+ * Typed service keys. Keys are frozen, compared by id, and carry a phantom
+ * type so require/optional return the provider's contract type.
+ */
+
+import { MalformedPluginError } from './errors';
+import type { RuntimeScope, ServiceKey } from './types';
+
+const VALID_SCOPES = new Set<string>(['process', 'agent', 'run']);
+
+export function serviceKey<T = unknown>(id: string, scope: RuntimeScope): ServiceKey<T> {
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new MalformedPluginError('service key id must be a non-empty string');
+  }
+  if (!VALID_SCOPES.has(scope)) {
+    throw new MalformedPluginError(`service key '${id}' has invalid scope '${String(scope)}'`);
+  }
+  return Object.freeze({ id, scope });
+}

package/src/kernel/types.ts

@@ -0,0 +1,317 @@
+/**
+ * Kernel public types.
+ *
+ * The kernel is an internal dependency-free composition layer. It must not
+ * import the AI SDK, Jean2 packages, Hono, SQLite, Bun product APIs, or any
+ * Capek product domain. See 04-plugin-contract.md for the guarantees these
+ * types describe.
+ */
+
+export type RuntimeScope = 'process' | 'agent' | 'run';
+
+/** A typed capability contract. Identity is the id; scope names where the
+ * service may be provided. */
+export interface ServiceKey<T = unknown> {
+  readonly id: string;
+  readonly scope: RuntimeScope;
+  readonly _type?: T;
+}
+
+export interface Disposable {
+  dispose(): void | Promise<void>;
+}
+
+/** A completion or persistence barrier awaited during scope disposal. */
+export type CleanupBarrier = PromiseLike<void> | (() => PromiseLike<void>);
+
+/** Explicitly replaces the provider named by replacedProvider for one key. */
+export interface ServiceOverride {
+  readonly key: ServiceKey<unknown>;
+  readonly replacedProvider: string;
+}
+
+/** A lifecycle unit that declares dependencies and contributes behavior. */
+export interface CapekPlugin<Options = unknown> {
+  readonly id: string;
+  readonly version?: string;
+  readonly scope: RuntimeScope;
+  readonly provides?: readonly ServiceKey<unknown>[];
+  readonly requires?: readonly ServiceKey<unknown>[];
+  readonly optional?: readonly ServiceKey<unknown>[];
+  readonly overrides?: readonly ServiceOverride[];
+  setup(
+    context: PluginContext,
+    options: Options,
+  ): void | Disposable | Promise<void | Disposable>;
+}
+
+/** An opaque model-facing tool payload. The kernel validates only that
+ * `name` is a non-empty string; `parameters`, `inputSchema`, and any
+ * additional fields are carried through untouched. */
+export interface ToolDefinition {
+  readonly name: string;
+  readonly description?: string;
+  readonly parameters?: Readonly<Record<string, unknown>>;
+  readonly inputSchema?: Readonly<Record<string, unknown>>;
+  readonly [extra: string]: unknown;
+}
+
+/** Optional visibility metadata for a tool. An explicit false hides the
+ * tool even when every required capability resolves; reason explains why. */
+export interface ToolVisibility {
+  readonly visible: boolean;
+  readonly reason?: string;
+}
+
+/** A model-facing tool contribution. Effective visibility combines an
+ * explicit visibility false with missing required capabilities, matched by
+ * service id and ServiceKey scope. Order is optional; omitted orders
+ * default to 0 and sort before explicitly ordered tools with plugin-id
+ * then contribution-id tie-breaks. */
+export interface ToolContribution {
+  readonly id: string;
+  readonly order?: number;
+  readonly definition: ToolDefinition;
+  /** Opaque product-layer payload (for capek: the exact `LoadedTool` this
+   * contribution advertises). The kernel never reads it; the effective-tool
+   * view carries it through unchanged. */
+  readonly payload?: unknown;
+  readonly requiredCapabilities?: readonly ServiceKey<unknown>[];
+  readonly visibility?: ToolVisibility;
+}
+
+export type ContextPhase =
+  | 'identity'
+  | 'preferences'
+  | 'instructions'
+  | 'workspace'
+  | 'capabilities'
+  | 'task';
+
+/** The build-time context handed to a section provider. `data` carries the
+ * opaque assembly options the caller passed to `buildContext(data?)`; the
+ * kernel validates only that it is an object when present and never reads
+ * its fields, so it stays dependency-free. Product layers type the data
+ * through the `TData` parameter and validate the concrete shape. */
+export interface ContextBuildContext<TData = unknown> {
+  readonly kind: RuntimeScope;
+  readonly data?: TData;
+}
+
+/** A context section contribution. Null omits the section without changing
+ * the ordering of the others. */
+export interface ContextSectionContribution<TData = unknown> {
+  readonly id: string;
+  readonly phase: ContextPhase;
+  readonly order: number;
+  provide(context: ContextBuildContext<TData>): string | null | Promise<string | null>;
+}
+
+export type RunTerminalOutcome = 'completed' | 'failed' | 'cancelled';
+
+export interface RunStartedEvent {
+  readonly type: 'run:started';
+  readonly runId: string;
+}
+
+export interface RunTerminalEvent {
+  readonly type: 'run:terminal';
+  readonly runId: string;
+  readonly outcome: RunTerminalOutcome;
+  readonly reason?: string;
+}
+
+export interface RunDisposedEvent {
+  readonly type: 'run:disposed';
+  readonly runId: string;
+}
+
+export interface KernelEventMap {
+  'run:started': RunStartedEvent;
+  'run:terminal': RunTerminalEvent;
+  'run:disposed': RunDisposedEvent;
+}
+
+export type KernelEventType = keyof KernelEventMap;
+export type KernelEvent = KernelEventMap[KernelEventType];
+
+/** An observer contribution for typed runtime events. Listeners are awaited
+ * in deterministic order during emit. */
+export interface EventListenerContribution {
+  readonly id: string;
+  readonly eventTypes: readonly KernelEventType[];
+  handle(event: KernelEvent): void | Promise<void>;
+}
+
+
+export type ScopeStatus = 'active' | 'disposing' | 'disposed';
+export type PluginStatus = 'pending' | 'active' | 'failed' | 'disposed';
+export type RunStatus = 'created' | 'running' | 'terminal' | 'disposed';
+
+export interface PluginDiagnostic {
+  readonly id: string;
+  readonly version?: string;
+  readonly scope: RuntimeScope;
+  readonly status: PluginStatus;
+}
+
+export interface ServiceDiagnostic {
+  readonly keyId: string;
+  readonly keyScope: RuntimeScope;
+  readonly providerPluginId: string;
+  readonly providerScope: RuntimeScope;
+}
+
+export interface ToolDiagnostic {
+  readonly id: string;
+  readonly order: number;
+  readonly pluginId: string;
+  readonly visible: boolean;
+  readonly hiddenReasons: readonly string[];
+}
+
+export interface ContextSectionDiagnostic {
+  readonly id: string;
+  readonly phase: ContextPhase;
+  readonly order: number;
+  readonly pluginId: string;
+  readonly scopeKind: RuntimeScope;
+}
+
+export interface ListenerDiagnostic {
+  readonly id: string;
+  readonly eventTypes: readonly KernelEventType[];
+  readonly pluginId: string;
+  readonly scopeKind: RuntimeScope;
+}
+
+
+/** Read-only composition inventory. Never contains plugin options or service
+ * values, so it is safe to surface to support and tests. */
+export interface ScopeDiagnosticsSnapshot {
+  readonly scopeId: string;
+  readonly kind: RuntimeScope;
+  readonly parentKind: RuntimeScope | null;
+  readonly status: ScopeStatus;
+  readonly plugins: readonly PluginDiagnostic[];
+  readonly services: readonly ServiceDiagnostic[];
+  readonly tools: readonly ToolDiagnostic[];
+  readonly contextSections: readonly ContextSectionDiagnostic[];
+  readonly listeners: readonly ListenerDiagnostic[];
+  readonly runId?: string;
+  readonly runStatus?: RunStatus;
+  readonly runOutcome?: RunTerminalOutcome;
+  readonly cleanupBarrierCount: number;
+}
+
+export interface CompositionDiagnostics {
+  snapshot(): ScopeDiagnosticsSnapshot;
+}
+
+/** The setup-time surface handed to plugins. Registrations return disposers
+ * owned by the installing scope. */
+export interface PluginContext {
+  readonly kind: RuntimeScope;
+  readonly scopeId: string;
+  provide<T>(key: ServiceKey<T>, service: T): Disposable;
+  require<T>(key: ServiceKey<T>): T;
+  optional<T>(key: ServiceKey<T>): T | undefined;
+  contributeTool(contribution: ToolContribution): Disposable;
+  contributeContext(contribution: ContextSectionContribution): Disposable;
+  /** The effective tool contributions of the current scope chain in
+   * deterministic order, including contributions registered earlier in
+   * setup. Narrow like buildContext: plugins never receive the scope
+   * handle just to inspect tools. */
+  listTools(): readonly EffectiveTool[];
+  /** Assembles the effective context sections of the current scope chain in
+   * deterministic order, including sections registered earlier in setup.
+   * Narrow by design: plugins never receive the scope handle just to build
+   * context. The optional `data` is passed through to section providers as
+   * `ContextBuildContext.data` after the kernel validates it is an object. */
+  buildContext<TData = unknown>(data?: TData): Promise<readonly ProvidedContextSection[]>;
+  contributeListener(contribution: EventListenerContribution): Disposable;
+  registerCleanupBarrier(barrier: CleanupBarrier): Disposable;
+  readonly diagnostics: CompositionDiagnostics;
+}
+
+export interface EffectiveTool {
+  readonly id: string;
+  readonly order: number;
+  readonly definition: ToolDefinition;
+  /** The contribution's opaque payload, carried through unchanged. */
+  readonly payload?: unknown;
+  readonly pluginId: string;
+  readonly visible: boolean;
+  readonly hiddenReasons: readonly string[];
+}
+
+export interface EffectiveContextSection {
+  readonly id: string;
+  readonly phase: ContextPhase;
+  readonly order: number;
+  readonly pluginId: string;
+  readonly scopeKind: RuntimeScope;
+}
+
+export interface ProvidedContextSection {
+  readonly id: string;
+  readonly phase: ContextPhase;
+  readonly content: string;
+}
+
+export interface ScopeHandle {
+  readonly kind: RuntimeScope;
+  readonly scopeId: string;
+  readonly parent: ScopeHandle | null;
+  /** Live child scopes. A disposed child unregisters from its parent, so
+   * this never retains closed scopes. */
+  readonly childCount: number;
+  require<T>(key: ServiceKey<T>): T;
+  optional<T>(key: ServiceKey<T>): T | undefined;
+  snapshot(): ScopeDiagnosticsSnapshot;
+  listTools(): readonly EffectiveTool[];
+  listContextSections(): readonly EffectiveContextSection[];
+  /** Assembles effective context sections in deterministic order. Null
+   * sections are omitted without shifting the others. The optional `data`
+   * must be an object when present and is passed through to every section
+   * provider as `ContextBuildContext.data`. */
+  buildContext<TData = unknown>(data?: TData): Promise<readonly ProvidedContextSection[]>;
+  dispose(): Promise<void>;
+}
+
+export interface RunCancellation {
+  /** True when this call moved the run from a live state to terminal. */
+  readonly acknowledged: boolean;
+  /** Resolves after terminal event dispatch, cleanup barriers, reverse
+   * disposal, and the disposed event. */
+  readonly completion: Promise<void>;
+}
+
+export interface ProcessScopeHandle extends ScopeHandle {
+  readonly kind: 'process';
+  createAgentScope(
+    plugins: readonly CapekPlugin[],
+    options?: PluginOptionsMap,
+  ): Promise<AgentScopeHandle>;
+}
+
+export interface AgentScopeHandle extends ScopeHandle {
+  readonly kind: 'agent';
+  createRunScope(
+    runId: string,
+    plugins: readonly CapekPlugin[],
+    options?: PluginOptionsMap,
+  ): Promise<RunScopeHandle>;
+}
+
+export interface RunScopeHandle extends ScopeHandle {
+  readonly kind: 'run';
+  readonly runId: string;
+  readonly runStatus: RunStatus;
+  start(): Promise<void>;
+  markTerminal(outcome: 'completed' | 'failed'): Promise<void>;
+  cancel(reason?: string): RunCancellation;
+  registerCleanupBarrier(barrier: CleanupBarrier): Disposable;
+}
+
+export type PluginOptionsMap = Readonly<Record<string, unknown>>;

package/src/memory/index.ts

@@ -0,0 +1,2 @@
+export * from './registry';
+export * from './memory-tool';

package/src/memory/memory-tool.ts

@@ -0,0 +1,75 @@
+import type { PermissionAsk, PermissionRiskLevel } from '@capekai/tool';
+import {
+  addEntry,
+  listEntries,
+  removeEntry,
+  replaceEntry,
+  MEMORY_LINE_MEMORY_TARGET,
+  MEMORY_LINE_NO_SECRETS,
+  MEMORY_LINE_ONLY_COMPACT,
+  MEMORY_LINE_USE_LIST,
+  MEMORY_LINE_USER_TARGET,
+  type MemoryActionResult,
+  type MemoryTarget,
+} from './registry';
+
+export const memoryToolDefinition = {
+  name: 'memory',
+  description: `Persist durable workspace knowledge across sessions.
+
+${MEMORY_LINE_USER_TARGET}
+${MEMORY_LINE_MEMORY_TARGET}
+
+Character limits: user=1500 chars, workspace=2500 chars. Keep entries compact.
+
+Actions:
+- list: Read current entries and char usage for a target. Requires target only.
+- add: Append a new bullet entry. Requires content.
+- replace: Find an entry by oldText substring and replace it. Requires oldText and content.
+- remove: Find an entry by oldText substring and remove it. Requires oldText.
+
+${MEMORY_LINE_USE_LIST}
+${MEMORY_LINE_ONLY_COMPACT}
+${MEMORY_LINE_NO_SECRETS}`,
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      action: { type: 'string' as const, enum: ['list', 'add', 'replace', 'remove'], description: 'The action to perform on the memory file.' },
+      target: { type: 'string' as const, enum: ['user', 'memory'], description: 'Which memory file to modify. "user" for preferences, "memory" for workspace facts.' },
+      content: { type: 'string' as const, description: 'The new content for add/replace actions.' },
+      oldText: { type: 'string' as const, description: 'The text to find for replace/remove actions. Must match exactly one entry.' },
+    },
+    required: ['action', 'target'],
+  },
+  timeout: 10000,
+};
+
+export async function executeMemoryTool(input: Record<string, unknown>, basePath: string, risk: PermissionRiskLevel, askFn?: (ask: PermissionAsk) => Promise<unknown>): Promise<MemoryActionResult> {
+  const action = input.action as 'list' | 'add' | 'replace' | 'remove';
+  const target = input.target as MemoryTarget;
+  const content = input.content as string | undefined;
+  const oldText = input.oldText as string | undefined;
+  if (!['list', 'add', 'replace', 'remove'].includes(action)) return { success: false, error: 'Invalid action. Must be list, add, replace, or remove.' };
+  if (!['user', 'memory'].includes(target)) return { success: false, error: 'Invalid target. Must be user or memory.' };
+  if (action === 'list') return listEntries(basePath, target);
+  if ((action === 'add' || action === 'replace') && typeof content !== 'string') {
+    return { success: false, error: `Content is required for ${action} action.` };
+  }
+  if ((action === 'replace' || action === 'remove') && typeof oldText !== 'string') {
+    return { success: false, error: `oldText is required for ${action} action.` };
+  }
+  if (risk !== 'none' && askFn) {
+    const approved = await askFn({
+      type: 'permission', question: `Allow memory ${action} on ${target}?`,
+      description: `Action: ${action}\nTarget: ${target}${content ? `\nContent: ${content.slice(0, 200)}` : ''}${oldText ? `\nOld text: ${oldText.slice(0, 200)}` : ''}`,
+      risk, resource: 'file', action: 'write', paths: [target === 'user' ? 'USER.md' : 'MEMORY.md'],
+    });
+    if (!approved) return { success: false, error: 'USER_REJECTION' };
+  }
+  if (action === 'add') return content ? addEntry(basePath, target, content) : { success: false, error: 'Content is required for add action.' };
+  if (action === 'replace') {
+    if (!oldText) return { success: false, error: 'oldText is required for replace action.' };
+    return content ? replaceEntry(basePath, target, oldText, content) : { success: false, error: 'Content is required for replace action.' };
+  }
+  return oldText ? removeEntry(basePath, target, oldText) : { success: false, error: 'oldText is required for remove action.' };
+}

package/src/memory/registry.ts

@@ -0,0 +1,172 @@
+import { existsSync } from 'fs';
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { join } from 'path';
+
+const USER_FILE = 'USER.md';
+const MEMORY_FILE = 'MEMORY.md';
+export const USER_CHAR_LIMIT = 1500;
+export const MEMORY_CHAR_LIMIT = 2500;
+export type MemoryTarget = 'user' | 'memory';
+
+export interface MemoryUsage { chars: number; limit: number }
+export interface MemoryFile {
+  path: string;
+  content: string;
+  entries: string[];
+  charCount: number;
+  charLimit: number;
+}
+export interface MemoryActionResult {
+  success: boolean;
+  result?: {
+    target: MemoryTarget;
+    action: 'list' | 'add' | 'replace' | 'remove';
+    path: string;
+    usage: MemoryUsage;
+    entry?: string;
+    entries?: string[];
+  };
+  error?: string;
+  entries?: string[];
+  usage?: MemoryUsage;
+}
+
+const fileName = (target: MemoryTarget) => target === 'user' ? USER_FILE : MEMORY_FILE;
+const filePath = (basePath: string, target: MemoryTarget) => join(basePath, fileName(target));
+const charLimit = (target: MemoryTarget) => target === 'user' ? USER_CHAR_LIMIT : MEMORY_CHAR_LIMIT;
+
+export function parseEntries(content: string): string[] {
+  return content.split('\n').map((line) => line.trim()).filter((line) => line.startsWith('- '));
+}
+export function entriesToContent(entries: string[]): string { return entries.join('\n'); }
+export function formatEntriesForDisplay(entries: string[]): string[] {
+  return entries.map((entry, index) => `[${index}] ${entry.replace(/^- /, '')}`);
+}
+export function formatMemorySection(tag: string, path: string, content: string, chars: number, limit: number): string {
+  return `<${tag} path="${path}" usage="${chars}/${limit}">\n${content}\n</${tag}>`;
+}
+
+export async function loadMemoryFile(basePath: string, target: MemoryTarget): Promise<MemoryFile | null> {
+  const path = filePath(basePath, target);
+  if (!existsSync(path)) return null;
+  try {
+    const content = (await readFile(path, 'utf-8')).trim();
+    if (!content) return null;
+    return { path: fileName(target), content, entries: parseEntries(content), charCount: content.length, charLimit: charLimit(target) };
+  } catch {
+    return null;
+  }
+}
+
+async function ensureDir(basePath: string): Promise<void> {
+  if (!existsSync(basePath)) await mkdir(basePath, { recursive: true });
+}
+
+function fullResult(existing: string, target: MemoryTarget, entries: string[], replaceHint: string): MemoryActionResult {
+  const limit = charLimit(target);
+  return {
+    success: false,
+    error: `Memory is full (${existing.length}/${limit} chars). Consider merging related entries to free space, or ${replaceHint}.`,
+    entries: formatEntriesForDisplay(entries),
+    usage: { chars: existing.length, limit },
+  };
+}
+
+export async function addEntry(basePath: string, target: MemoryTarget, content: string): Promise<MemoryActionResult> {
+  const trimmed = content.trim();
+  if (!trimmed) return { success: false, error: 'Content cannot be empty.' };
+  const entry = `- ${trimmed}`;
+  const path = filePath(basePath, target);
+  let existingContent = '';
+  let entries: string[] = [];
+  if (existsSync(path)) {
+    try {
+      existingContent = (await readFile(path, 'utf-8')).trim();
+      entries = parseEntries(existingContent);
+    } catch {
+      existingContent = '';
+      entries = [];
+    }
+  }
+  if (entries.includes(entry)) return { success: false, error: 'Exact duplicate entry already exists.' };
+  const next = existingContent ? `${existingContent}\n${entry}` : entry;
+  if (next.length > charLimit(target)) return fullResult(existingContent, target, entries, 'replace/remove existing ones first');
+  await ensureDir(basePath);
+  await writeFile(path, next, 'utf-8');
+  return { success: true, result: { target, action: 'add', path: fileName(target), usage: { chars: next.length, limit: charLimit(target) }, entry: trimmed } };
+}
+
+async function readExisting(basePath: string, target: MemoryTarget): Promise<{ content: string; entries: string[] } | MemoryActionResult> {
+  const path = filePath(basePath, target);
+  if (!existsSync(path)) return { success: false, error: 'Memory file does not exist.' };
+  try {
+    const content = (await readFile(path, 'utf-8')).trim();
+    return { content, entries: parseEntries(content) };
+  } catch {
+    return { success: false, error: 'Failed to read memory file.' };
+  }
+}
+
+function findOne(content: string, entries: string[], target: MemoryTarget, oldText: string): string | MemoryActionResult {
+  const matches = entries.filter((entry) => entry.includes(oldText));
+  const usage = { chars: content.length, limit: charLimit(target) };
+  if (matches.length === 0) return { success: false, error: `No entry found matching "${oldText}". Use the list action to see current entries.`, entries: formatEntriesForDisplay(entries), usage };
+  if (matches.length > 1) return { success: false, error: `Multiple entries match "${oldText}". Be more specific.`, entries: formatEntriesForDisplay(matches), usage };
+  return matches[0];
+}
+
+export async function replaceEntry(basePath: string, target: MemoryTarget, oldText: string, content: string): Promise<MemoryActionResult> {
+  const trimmed = content.trim();
+  if (!trimmed) return { success: false, error: 'New content cannot be empty.' };
+  const loaded = await readExisting(basePath, target);
+  if ('success' in loaded) return loaded;
+  const match = findOne(loaded.content, loaded.entries, target, oldText);
+  if (typeof match !== 'string') return match;
+  const next = loaded.content.replace(match, `- ${trimmed}`);
+  if (next.length > charLimit(target)) return fullResult(loaded.content, target, loaded.entries, 'remove existing ones first');
+  await writeFile(filePath(basePath, target), next, 'utf-8');
+  return { success: true, result: { target, action: 'replace', path: fileName(target), usage: { chars: next.length, limit: charLimit(target) }, entry: trimmed } };
+}
+
+export async function removeEntry(basePath: string, target: MemoryTarget, oldText: string): Promise<MemoryActionResult> {
+  const loaded = await readExisting(basePath, target);
+  if ('success' in loaded) return loaded;
+  const match = findOne(loaded.content, loaded.entries, target, oldText);
+  if (typeof match !== 'string') return match;
+  const lines = loaded.content.split('\n');
+  const matchIndex = lines.findIndex((line) => line.trim() === match);
+  const next = matchIndex >= 0
+    ? [...lines.slice(0, matchIndex), ...lines.slice(matchIndex + 1)].join('\n').trim()
+    : loaded.content;
+  await writeFile(filePath(basePath, target), next, 'utf-8');
+  return { success: true, result: { target, action: 'remove', path: fileName(target), usage: { chars: next.length, limit: charLimit(target) } } };
+}
+
+export async function listEntries(basePath: string, target: MemoryTarget): Promise<MemoryActionResult> {
+  const file = await loadMemoryFile(basePath, target);
+  return { success: true, result: { target, action: 'list', path: fileName(target), usage: { chars: file?.charCount ?? 0, limit: charLimit(target) }, entries: file ? formatEntriesForDisplay(file.entries) : [] } };
+}
+
+export async function loadMemoryInstructions(basePath: string): Promise<string | null> {
+  const sections: string[] = [];
+  const user = await loadMemoryFile(basePath, 'user');
+  if (user) sections.push(formatMemorySection('user_memory', user.path, user.content, user.charCount, user.charLimit));
+  const memory = await loadMemoryFile(basePath, 'memory');
+  if (memory) sections.push(formatMemorySection('workspace_memory', memory.path, memory.content, memory.charCount, memory.charLimit));
+  return sections.length > 0 ? sections.join('\n\n') : null;
+}
+
+export const MEMORY_LINE_USER_TARGET = 'Use target="user" for user preferences and communication/workflow expectations.';
+export const MEMORY_LINE_MEMORY_TARGET = 'Use target="memory" for workspace facts, repo conventions, commands, lessons, and non-obvious fixes.';
+export const MEMORY_LINE_ONLY_COMPACT = 'Only save compact facts that should affect future sessions.';
+export const MEMORY_LINE_NO_SECRETS = 'Do not save secrets, raw logs, large code, or one-off details.';
+export const MEMORY_LINE_USE_LIST = 'Use list before replace/remove to see the exact current entries and avoid guesswork.';
+
+export const MEMORY_GUIDANCE = `You can persist durable workspace knowledge using the memory tool.
+${MEMORY_LINE_USER_TARGET}
+${MEMORY_LINE_MEMORY_TARGET}
+Character limits: user=${USER_CHAR_LIMIT}, workspace=${MEMORY_CHAR_LIMIT}.
+${MEMORY_LINE_ONLY_COMPACT}
+${MEMORY_LINE_NO_SECRETS}
+If memory is full, consolidate existing entries with replace before adding.
+Use the list action to verify current entries before replacing or removing.`;

package/src/permission/ask-user-api.ts

@@ -0,0 +1,70 @@
+/**
+ * C6 generic ask surface over the NON-REPLACEABLE permission runtime.
+ * These exports preserve the exact pre-C6 `tools/ask-user-api.ts`
+ * identities; the state and decisions resolve through
+ * `getPermissionRuntimeService()`, so a composed agent scope owns its
+ * pending asks and timers while unscoped consumers keep the process-default
+ * behavior.
+ */
+
+import type { AskApi } from '@capekai/tool'
+import type { AskAuthority } from '@capekai/types';
+import type { PendingAskRecord } from '../runtime/host';
+import { ASK_TIMEOUT } from './policy';
+import { getPermissionRuntimeService } from './runtime';
+import type { AskBroadcastFn } from './contracts';
+
+export { ASK_TIMEOUT };
+export type { AskBroadcastFn };
+
+export function createAskApi(
+  sessionId: string,
+  toolCallId: string,
+  toolName: string,
+  broadcastFn: AskBroadcastFn,
+  workspaceId?: string,
+  rootSessionId?: string,
+): AskApi {
+  return getPermissionRuntimeService().createAskApi(
+    sessionId,
+    toolCallId,
+    toolName,
+    broadcastFn,
+    workspaceId,
+    rootSessionId,
+  );
+}
+
+export async function resolveAsk(toolCallId: string, response: unknown, requestId?: string): Promise<boolean> {
+  return getPermissionRuntimeService().resolveAsk(toolCallId, response, requestId);
+}
+
+export async function rejectAsk(toolCallId: string, error: Error): Promise<boolean> {
+  return getPermissionRuntimeService().rejectAsk(toolCallId, error);
+}
+
+export async function rejectPendingAsksByToolCallId(toolCallId: string, error?: Error): Promise<string[]> {
+  return getPermissionRuntimeService().rejectPendingAsksByToolCallId(toolCallId, error);
+}
+
+export async function rejectPendingAsksBySession(sessionId: string, error?: Error): Promise<string[]> {
+  return getPermissionRuntimeService().rejectPendingAsksBySession(sessionId, error);
+}
+
+export function hasPendingAsk(toolCallId: string): boolean {
+  return getPermissionRuntimeService().hasPendingAsk(toolCallId);
+}
+
+export function getAuthorityForPendingAsk(toolCallId: string): AskAuthority | undefined {
+  return getPermissionRuntimeService().getAuthorityForPendingAsk(toolCallId);
+}
+
+export async function getSessionIdForPendingAsk(toolCallId: string, requestId?: string): Promise<string | null> {
+  return getPermissionRuntimeService().getSessionIdForPendingAsk(toolCallId, requestId);
+}
+
+export const listPendingAsksBySession = (sessionId: string): Promise<PendingAskRecord[]> =>
+  getPermissionRuntimeService().listPendingAsksBySession(sessionId);
+
+export const listPendingAsksByRootSession = (rootSessionId: string): Promise<PendingAskRecord[]> =>
+  getPermissionRuntimeService().listPendingAsksByRootSession(rootSessionId);