@capekai/core 1.0.0

package/src/configuration/single-model.ts

@@ -0,0 +1,75 @@
+import type { RuntimeConfiguration } from './contracts';
+import { createDefaultRuntimeConfiguration } from './defaults';
+
+export interface ModelSpecifierSelection {
+  modelId: string;
+  providerId: string;
+}
+
+/** Splits a `provider/model` string on the first separator; the provider
+ * part is kept as-is (matching `parseModelSpecifier` for known provider
+ * ids); a bare model gets no provider. Self-contained so the
+ * configuration leaf concern stays import-clean. */
+export function resolveModelSpecifier(model: string): ModelSpecifierSelection {
+  const separator = model.indexOf('/');
+  if (separator <= 0 || separator === model.length - 1) {
+    return { modelId: model, providerId: 'openai' };
+  }
+  return {
+    providerId: model.slice(0, separator),
+    modelId: model.slice(separator + 1),
+  };
+}
+
+/** A starter `RuntimeConfiguration` for exactly one model string: wraps the
+ * package defaults, answers `findModel` for the given selection with a
+ * synthetic 128k entry, exposes it through `getModelsConfig`, and resolves
+ * API keys from the conventional `<PROVIDER>_API_KEY` env vars. Copy and
+ * extend when you outgrow one model. */
+export function createSingleModelConfiguration(selection: ModelSpecifierSelection): RuntimeConfiguration {
+  const defaults = createDefaultRuntimeConfiguration();
+  return {
+    ...defaults,
+    findModel(modelId, providerId) {
+      const found = defaults.findModel(modelId, providerId);
+      if (found) return found;
+      if (modelId !== selection.modelId || (providerId && providerId !== selection.providerId)) return undefined;
+      return {
+        id: selection.modelId,
+        name: selection.modelId,
+        contextWindow: 128_000,
+        maxOutputTokens: 16_384,
+        tier: 'standard',
+        providerId: selection.providerId,
+        providerName: selection.providerId,
+      };
+    },
+    getModelsConfig() {
+      const base = defaults.getModelsConfig();
+      const providers = base.providers.map((provider) => ({ ...provider, models: [...provider.models] }));
+      let provider = providers.find((candidate) => candidate.id === selection.providerId);
+      if (!provider) {
+        provider = { id: selection.providerId, name: selection.providerId, models: [] };
+        providers.push(provider);
+      }
+      if (!provider.models.some((candidate) => candidate.id === selection.modelId)) {
+        provider.models.push({
+          id: selection.modelId,
+          name: selection.modelId,
+          contextWindow: 128_000,
+          maxOutputTokens: 16_384,
+          tier: 'standard',
+        });
+      }
+      return {
+        providers,
+        defaultModel: selection.modelId,
+        defaultProvider: selection.providerId,
+      };
+    },
+    getApiKey(providerId) {
+      const conventional = process.env[`${providerId.toUpperCase().replaceAll('-', '_')}_API_KEY`];
+      return conventional ?? defaults.getApiKey(providerId);
+    },
+  };
+}

package/src/context/assembler.ts

@@ -0,0 +1,112 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Preconfig } from '@capekai/types';
+
+/**
+ * Context assembler contract and runtime accessors.
+ *
+ * The runtime core depends on this contract only: `getContextAssembler()`
+ * resolves the assembler seeded for the active agent scope and `build()` is
+ * the single entry point for ordered context assembly. The ordered
+ * implementation lives in the plugin layer; the legacy fixed builder stays a
+ * migration adapter and is never imported by the runtime core.
+ */
+
+/** Assembly options passed to every ordered context build. This is the exact
+ * option set the fixed builder consumed; no new task content is allowed. */
+export interface ContextAssemblyData {
+  preconfig: Preconfig;
+  workspacePath?: string;
+  workspaceId?: string;
+  additionalPaths?: string[];
+  selfDelegationAvailable?: boolean;
+}
+
+/** The required runtime service contract for context assembly. */
+export interface ContextAssembler {
+  readonly id: string;
+  build(data: ContextAssemblyData): Promise<string>;
+}
+
+/** Malformed assembly options fail predictably with this error instead of
+ * surfacing unsafe property access deep inside a section provider. */
+export class ContextAssemblyDataError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+/** Validates the typed assembly options contract. Returns the data unchanged
+ * so callers can pass the validated value onward without casts. */
+export function validateContextAssemblyData(data: unknown): ContextAssemblyData {
+  if (typeof data !== 'object' || data === null) {
+    throw new ContextAssemblyDataError('context assembly data must be an object');
+  }
+  const candidate = data as Partial<ContextAssemblyData>;
+  const preconfig = candidate.preconfig;
+  if (typeof preconfig !== 'object' || preconfig === null) {
+    throw new ContextAssemblyDataError('context assembly data preconfig must be an object');
+  }
+  if (typeof (preconfig as { id?: unknown }).id !== 'string') {
+    throw new ContextAssemblyDataError('context assembly data preconfig must declare a string id');
+  }
+  const systemPrompt = (preconfig as { systemPrompt?: unknown }).systemPrompt;
+  if (systemPrompt !== undefined && typeof systemPrompt !== 'string') {
+    throw new ContextAssemblyDataError(
+      'context assembly data preconfig systemPrompt must be a string when present',
+    );
+  }
+  for (const key of ['workspacePath', 'workspaceId'] as const) {
+    const value = candidate[key];
+    if (value !== undefined && typeof value !== 'string') {
+      throw new ContextAssemblyDataError(
+        `context assembly data ${key} must be a string when present`,
+      );
+    }
+  }
+  const additionalPaths = candidate.additionalPaths;
+  if (
+    additionalPaths !== undefined
+    && (!Array.isArray(additionalPaths) || additionalPaths.some((entry) => typeof entry !== 'string'))
+  ) {
+    throw new ContextAssemblyDataError(
+      'context assembly data additionalPaths must be an array of strings when present',
+    );
+  }
+  const selfDelegationAvailable = candidate.selfDelegationAvailable;
+  if (selfDelegationAvailable !== undefined && typeof selfDelegationAvailable !== 'boolean') {
+    throw new ContextAssemblyDataError(
+      'context assembly data selfDelegationAvailable must be a boolean when present',
+    );
+  }
+  return candidate as ContextAssemblyData;
+}
+
+const scopedAssembler = new AsyncLocalStorage<ContextAssembler>();
+
+/** Fallback used when no composed scope has seeded an assembler. The plugin
+ * layer installs the fixed legacy builder adapter here, so consumers that
+ * run outside `enterAgentScope` (the current Jean2 server path) keep the
+ * exact pre-C3 behavior until they adopt the composed entry. */
+let defaultAssembler: ContextAssembler | undefined;
+
+export function setDefaultContextAssembler(assembler: ContextAssembler): void {
+  defaultAssembler = assembler;
+}
+
+/** Resolves the assembler seeded for the active agent scope, falling back to
+ * the default assembler for consumers that run outside a composed scope. */
+export function getContextAssembler(): ContextAssembler {
+  const assembler = scopedAssembler.getStore() ?? defaultAssembler;
+  if (assembler === undefined) {
+    throw new Error(
+      'no ContextAssembler is active and no default assembler is installed',
+    );
+  }
+  return assembler;
+}
+
+/** Seeds the active agent scope's assembler for the callback duration. */
+export function withContextAssembler<T>(assembler: ContextAssembler, callback: () => T): T {
+  return scopedAssembler.run(assembler, callback);
+}

package/src/context/index.ts

@@ -0,0 +1,2 @@
+export * from './sources';
+export * from './workspace';

package/src/context/sources.ts

@@ -0,0 +1,119 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import type { Preconfig } from '@capekai/types';
+
+export interface LoadedInstructions {
+  global: string | null;
+  project: string | null;
+}
+
+export interface PreconfigSource {
+  get(id: string): Promise<Preconfig | null>;
+  getDefault(): Promise<Preconfig | null>;
+  getForAgent(id: string): Promise<Preconfig | null>;
+  list(): Promise<Preconfig[]>;
+  listSubagents(): Promise<Preconfig[]>;
+}
+
+export interface AgentSource {
+  getDirectory(id: string): Promise<string | null>;
+  readMemoryFile(id: string, filename: 'USER.md' | 'MEMORY.md'): Promise<string | null>;
+}
+
+export interface InstructionSource {
+  getGlobalPath(): string | undefined;
+}
+
+export interface ContextSources {
+  preconfigs: PreconfigSource;
+  agents: AgentSource;
+  instructions: InstructionSource;
+}
+
+const defaultPreconfigs: PreconfigSource = {
+  async get() { return null; },
+  async getDefault() { return null; },
+  async getForAgent() { return null; },
+  async list() { return []; },
+  async listSubagents() { return []; },
+};
+
+const defaultAgents: AgentSource = {
+  async getDirectory() { return null; },
+  async readMemoryFile() { return null; },
+};
+
+const defaultInstructions: InstructionSource = { getGlobalPath: () => undefined };
+let preconfigs = defaultPreconfigs;
+let agents = defaultAgents;
+let instructions = defaultInstructions;
+const scopedSources = new AsyncLocalStorage<ContextSources>();
+
+function activeSources(): ContextSources {
+  return scopedSources.getStore() ?? { preconfigs, agents, instructions };
+}
+
+export function getContextSources(): ContextSources {
+  return activeSources();
+}
+
+export function withContextSources<T>(
+  value: Partial<ContextSources>,
+  callback: () => T,
+): T {
+  return scopedSources.run({
+    preconfigs: value.preconfigs ?? defaultPreconfigs,
+    agents: value.agents ?? defaultAgents,
+    instructions: value.instructions ?? defaultInstructions,
+  }, callback);
+}
+
+export function configurePreconfigSource(value?: PreconfigSource): void {
+  preconfigs = value ?? defaultPreconfigs;
+}
+
+export function configureAgentSource(value?: AgentSource): void {
+  agents = value ?? defaultAgents;
+}
+
+export function configureInstructionSource(value?: InstructionSource): void {
+  instructions = value ?? defaultInstructions;
+}
+
+export const getPreconfig = (id: string) => activeSources().preconfigs.get(id);
+export const getDefaultPreconfig = () => activeSources().preconfigs.getDefault();
+export const getPreconfigOrAgent = (id: string) => activeSources().preconfigs.getForAgent(id);
+export const listPreconfigs = () => activeSources().preconfigs.list();
+export const listSubagentPreconfigs = () => activeSources().preconfigs.listSubagents();
+export const getAgentDirectory = (id: string) => activeSources().agents.getDirectory(id);
+export const readAgentMemoryFile = (id: string, filename: 'USER.md' | 'MEMORY.md') =>
+  activeSources().agents.readMemoryFile(id, filename);
+
+async function readTrimmed(path: string | undefined, label: string): Promise<string | null> {
+  if (!path || !existsSync(path)) return null;
+  try {
+    const content = (await readFile(path, 'utf-8')).trim();
+    return content || null;
+  } catch (error: unknown) {
+    console.error(`Failed to read ${label} instructions:`, error);
+    return null;
+  }
+}
+
+export async function loadInstructions(workspacePath?: string): Promise<LoadedInstructions> {
+  return {
+    global: await readTrimmed(activeSources().instructions.getGlobalPath(), 'global'),
+    project: workspacePath
+      ? await readTrimmed(join(workspacePath, 'AGENTS.md'), 'project')
+      : null,
+  };
+}
+
+export function formatInstructions(value: LoadedInstructions): string | null {
+  const sections: string[] = [];
+  if (value.global) sections.push(`<instructions source="global">\n${value.global}\n</instructions>`);
+  if (value.project) sections.push(`<instructions source="project">\n${value.project}\n</instructions>`);
+  return sections.length > 0 ? sections.join('\n\n') : null;
+}

package/src/context/workspace.ts

@@ -0,0 +1,63 @@
+export function buildWorkspaceSystemPrompt(
+  workspacePath: string,
+  additionalPaths: string[] = [],
+): string {
+  let additionalSection = '';
+  if (additionalPaths.length > 0) {
+    additionalSection = `
+
+### Additional Paths
+
+This workspace has additional directories you have full access to:
+${additionalPaths.map((path) => `- ${path}`).join('\n')}
+
+You can read, write, search, and explore files in these directories using absolute paths.
+Relative paths still resolve from the primary workspace. Use absolute paths for additional paths.
+
+`;
+  }
+
+  return `
+<workspace>
+## Working Directory
+
+You are operating in: ${workspacePath}
+
+### Path Resolution
+
+All file operations support three path types:
+
+1. **Relative Paths** (RECOMMENDED for workspace files)
+   - Input: "src/app.ts"
+   - Resolves to: "${workspacePath}/src/app.ts"
+
+2. **Absolute Paths**
+   - Input: "${workspacePath}/src/app.ts"
+   - Used as-is
+
+3. **Home Paths**
+   - Input: "~/Documents/file.txt"
+   - Expands relative to the current user's home directory
+
+### Default Behaviors
+
+- **File Operations**: Relative paths resolve from workspace root
+- **Shell Commands**: Execute from workspace root by default
+- **Search Operations**: Scoped to workspace by default
+${additionalSection}### Security
+
+Operations outside the workspace directory require explicit approval:
+- Writing outside workspace: Requires approval
+- Reading outside workspace: Requires approval (configurable)
+- System directories: Blocked
+
+### Best Practices
+
+1. Use relative paths for files within the workspace
+2. Use the \`cwd\` parameter in shell commands instead of \`cd\`
+3. When in doubt, use absolute paths
+
+Current workspace: ${workspacePath}
+</workspace>
+`.trim();
+}