@flowcodex/core 0.3.0

package/src/kernel/pipeline.ts

@@ -0,0 +1,152 @@
+export type NextFn<T> = (value: T) => Promise<T>;
+export type MiddlewareHandler<T> = (value: T, next: NextFn<T>) => Promise<T>;
+
+export type PipelineErrorPolicy = 'rethrow' | 'swallow';
+
+export interface PipelineErrorEvent {
+  middleware: string;
+  owner?: string | undefined;
+  err: unknown;
+}
+
+export type PipelineErrorHandler = (
+  ev: PipelineErrorEvent,
+) => PipelineErrorPolicy | Promise<PipelineErrorPolicy>;
+
+export interface Middleware<T> {
+  name: string;
+  handler: MiddlewareHandler<T>;
+  owner?: string | undefined;
+}
+
+export interface PipelineOptions {
+  optional?: boolean | undefined;
+}
+
+export interface ReadonlyPipeline<T> {
+  readonly size: number;
+  list(): readonly string[];
+  run(input: T): Promise<T>;
+}
+
+export class Pipeline<T> {
+  private readonly chain: Middleware<T>[] = [];
+  private errorHandler?: PipelineErrorHandler | undefined;
+
+  setErrorHandler(handler: PipelineErrorHandler | undefined): this {
+    this.errorHandler = handler;
+    return this;
+  }
+
+  use(mw: Middleware<T> | Middleware<unknown>): this {
+    this.ensureUnique(mw.name);
+    this.chain.push(mw as Middleware<T>);
+    return this;
+  }
+
+  prepend(mw: Middleware<T>): this {
+    this.ensureUnique(mw.name);
+    this.chain.unshift(mw);
+    return this;
+  }
+
+  insertAt(index: number, mw: Middleware<T>): this {
+    this.ensureUnique(mw.name);
+    const idx = Math.max(0, Math.min(index, this.chain.length));
+    this.chain.splice(idx, 0, mw);
+    return this;
+  }
+
+  insertBefore(target: string, mw: Middleware<T>, opts?: PipelineOptions): this {
+    this.ensureUnique(mw.name);
+    const idx = this.indexOf(target, opts?.optional);
+    if (idx === -1) return this;
+    this.chain.splice(idx, 0, mw);
+    return this;
+  }
+
+  insertAfter(target: string, mw: Middleware<T>, opts?: PipelineOptions): this {
+    this.ensureUnique(mw.name);
+    const idx = this.indexOf(target, opts?.optional);
+    if (idx === -1) return this;
+    this.chain.splice(idx + 1, 0, mw);
+    return this;
+  }
+
+  replace(target: string, mw: Middleware<T>, opts?: PipelineOptions): this {
+    if (mw.name !== target) this.ensureUnique(mw.name);
+    const idx = this.indexOf(target, opts?.optional);
+    if (idx === -1) return this;
+    this.chain[idx] = mw;
+    return this;
+  }
+
+  remove(name: string, opts?: PipelineOptions): this {
+    const idx = this.indexOf(name, opts?.optional);
+    if (idx === -1) return this;
+    this.chain.splice(idx, 1);
+    return this;
+  }
+
+  list(): readonly string[] {
+    return this.chain.map((m) => m.name);
+  }
+
+  size(): number {
+    return this.chain.length;
+  }
+
+  asReadonly(): ReadonlyPipeline<T> {
+    const self = this;
+    return Object.freeze({
+      get size() {
+        return self.size();
+      },
+      list() {
+        return Object.freeze(self.list());
+      },
+      run(input: T) {
+        return self.run(input);
+      },
+    });
+  }
+
+  async run(input: T): Promise<T> {
+    let index = -1;
+    const chain = this.chain;
+    const errorHandler = this.errorHandler;
+
+    const dispatch = async (i: number, value: T): Promise<T> => {
+      if (i <= index) {
+        throw new Error(`Pipeline: next() called multiple times in "${chain[index]?.name}"`);
+      }
+      index = i;
+      const mw = chain[i];
+      if (!mw) return value;
+      try {
+        return await mw.handler(value, (v) => dispatch(i + 1, v));
+      } catch (err) {
+        if (!errorHandler) throw err;
+        const policy = await errorHandler({ middleware: mw.name, owner: mw.owner, err });
+        if (policy === 'rethrow') throw err;
+        return value;
+      }
+    };
+
+    return dispatch(0, input);
+  }
+
+  private indexOf(name: string, optional = false): number {
+    const idx = this.chain.findIndex((m) => m.name === name);
+    if (idx === -1 && !optional) {
+      throw new Error(`Pipeline: middleware "${name}" not found`);
+    }
+    return idx;
+  }
+
+  private ensureUnique(name: string): void {
+    if (this.chain.some((m) => m.name === name)) {
+      throw new Error(`Pipeline: middleware "${name}" already registered`);
+    }
+  }
+}

package/src/kernel/run-controller.ts

@@ -0,0 +1,85 @@
+import { toErrorMessage } from '../utils/error.js';
+
+export interface RunControllerOptions {
+  parentSignal?: AbortSignal | undefined;
+  errorSink?: (err: unknown, where: string) => void;
+}
+
+export class RunController {
+  private readonly ctrl = new AbortController();
+  private readonly hooks: Array<() => void | Promise<void>> = [];
+  private disposed = false;
+  private hooksDrained = false;
+  private readonly errorSink: (err: unknown, where: string) => void;
+
+  constructor(opts: RunControllerOptions = {}) {
+    this.errorSink =
+      opts.errorSink ??
+      ((err, where) => {
+        console.warn(JSON.stringify({
+          level: 'warn',
+          event: 'run.cleanup_hook_failed',
+          where,
+          message: toErrorMessage(err),
+          timestamp: new Date().toISOString(),
+        }));
+      });
+    if (opts.parentSignal) {
+      const parent = opts.parentSignal;
+      if (parent.aborted) {
+        this.ctrl.abort(parent.reason);
+      } else {
+        const onParentAbort = () => this.ctrl.abort(parent.reason);
+        parent.addEventListener('abort', onParentAbort, { once: true });
+        this.onAbort(() => parent.removeEventListener('abort', onParentAbort));
+      }
+    }
+    this.ctrl.signal.addEventListener(
+      'abort',
+      () => {
+        void this.runHooks();
+      },
+      { once: true },
+    );
+  }
+
+  get signal(): AbortSignal {
+    return this.ctrl.signal;
+  }
+
+  get aborted(): boolean {
+    return this.ctrl.signal.aborted;
+  }
+
+  abort(reason?: unknown): void {
+    if (this.ctrl.signal.aborted) return;
+    this.ctrl.abort(reason);
+  }
+
+  onAbort(fn: () => void | Promise<void>): () => void {
+    this.hooks.push(fn);
+    return () => {
+      const idx = this.hooks.indexOf(fn);
+      if (idx !== -1) this.hooks.splice(idx, 1);
+    };
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    await this.runHooks();
+  }
+
+  private async runHooks(): Promise<void> {
+    if (this.hooksDrained) return;
+    this.hooksDrained = true;
+    const snapshot = this.hooks.splice(0, this.hooks.length).reverse();
+    for (const hook of snapshot) {
+      try {
+        await hook();
+      } catch (err) {
+        this.errorSink(err, 'RunController.dispose');
+      }
+    }
+  }
+}

package/src/kernel/tokens.ts

@@ -0,0 +1,21 @@
+import type { Token } from './container.js';
+
+const t = <T>(name: string): Token<T> => Symbol(name) as Token<T>;
+
+export const TOKENS = {
+  Logger: t<unknown>('Logger'),
+  TokenCounter: t<unknown>('TokenCounter'),
+  SessionStore: t<unknown>('SessionStore'),
+  ConfigStore: t<unknown>('ConfigStore'),
+  ConfigLoader: t<unknown>('ConfigLoader'),
+  PermissionPolicy: t<unknown>('PermissionPolicy'),
+  Compactor: t<unknown>('Compactor'),
+  PathResolver: t<unknown>('PathResolver'),
+  Renderer: t<unknown>('Renderer'),
+  InputReader: t<unknown>('InputReader'),
+  ErrorHandler: t<unknown>('ErrorHandler'),
+  RetryPolicy: t<unknown>('RetryPolicy'),
+  SystemPromptBuilder: t<unknown>('SystemPromptBuilder'),
+  SecretScrubber: t<unknown>('SecretScrubber'),
+  ProviderRunner: t<unknown>('ProviderRunner'),
+} as const;

package/src/security/index.ts

@@ -0,0 +1,13 @@
+export {
+  DefaultPermissionPolicy,
+  matchGlob,
+} from './permission-policy.js';
+export type {
+  PermissionSource,
+  PermissionDecision,
+  TrustRule,
+  TrustFile,
+  PermissionPolicy,
+  ConfirmAwaiter,
+  DefaultPermissionPolicyOptions,
+} from './permission-policy.js';

package/src/security/permission-policy.ts

@@ -0,0 +1,273 @@
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import type { EventBus } from '../kernel/events.js';
+import { restrictFilePermissions } from '../session/secret-vault.js';
+import type { Permission, RiskTier, Tool, ToolContext } from '../types/tool.js';
+
+export type PermissionSource =
+  | 'default'
+  | 'trust'
+  | 'yolo'
+  | 'user'
+  | 'deny'
+  | 'subagent_guard';
+
+export interface PermissionDecision {
+  permission: Permission;
+  reason?: string | undefined;
+  source: PermissionSource;
+  riskTier?: RiskTier | undefined;
+}
+
+export interface TrustRule {
+  tool: string;
+  pattern: string;
+}
+
+export interface TrustFile {
+  allow: TrustRule[];
+  deny: TrustRule[];
+  yolo: boolean;
+}
+
+export interface PermissionPolicy {
+  evaluate(tool: Tool, input: unknown, ctx?: ToolContext): Promise<PermissionDecision>;
+  trust(rule: TrustRule): Promise<void>;
+  deny(rule: TrustRule): Promise<void>;
+  allowOnce(rule: TrustRule): void;
+  denyOnce(rule: TrustRule): void;
+  reload(): Promise<void>;
+  getYolo(): boolean;
+  setYolo(v: boolean): void;
+}
+
+export type ConfirmAwaiter = (
+  tool: Tool,
+  input: unknown,
+  toolUseId: string,
+  suggestedPattern: string,
+) => Promise<'yes' | 'no' | 'always' | 'deny'>;
+
+const DANGEROUS_CAPABILITIES = new Set([
+  'shell.arbitrary',
+  'fs.write.outside-project',
+  'net.outbound',
+  'package.install',
+  'config.mutate',
+]);
+
+const EMPTY_TRUST: TrustFile = { allow: [], deny: [], yolo: false };
+
+export interface DefaultPermissionPolicyOptions {
+  homeDir: string;
+  projectRoot: string;
+  events?: EventBus | undefined;
+  subagentGuard?: boolean | undefined;
+}
+
+export class DefaultPermissionPolicy implements PermissionPolicy {
+  private homeFile: string;
+  private projectFile: string;
+  private events?: EventBus | undefined;
+  private subagentGuard: boolean;
+  private trustFile: TrustFile = { ...EMPTY_TRUST };
+  private readonly sessionAllow: Set<string> = new Set();
+  private readonly sessionDeny: Set<string> = new Set();
+
+  constructor(opts: DefaultPermissionPolicyOptions) {
+    this.homeFile = path.join(opts.homeDir, 'trust.json');
+    this.projectFile = path.join(opts.projectRoot, '.flowcodex', 'trust.json');
+    this.events = opts.events;
+    this.subagentGuard = opts.subagentGuard ?? false;
+  }
+
+  async load(): Promise<void> {
+    this.trustFile = await this.readMerged();
+  }
+
+  async reload(): Promise<void> {
+    this.trustFile = await this.readMerged();
+  }
+
+  async evaluate(tool: Tool, input: unknown): Promise<PermissionDecision> {
+    const subject = extractSubject(tool, input);
+
+    if (this.matchesSession(this.sessionDeny, tool.name, subject)) {
+      return { permission: 'deny', reason: 'denied once this session', source: 'user' };
+    }
+    if (this.matchesRules(this.trustFile.deny, tool.name, subject)) {
+      return { permission: 'deny', reason: 'denied by trust rule', source: 'deny', riskTier: tool.riskTier };
+    }
+    if (this.matchesSession(this.sessionAllow, tool.name, subject)) {
+      return { permission: 'auto', reason: 'allowed once this session', source: 'user' };
+    }
+    if (this.matchesRules(this.trustFile.allow, tool.name, subject)) {
+      return { permission: 'auto', reason: 'allowed by trust rule', source: 'trust', riskTier: tool.riskTier };
+    }
+
+    let permission: Permission = tool.permission;
+    let source: PermissionSource = 'default';
+
+    if (
+      permission === 'auto' &&
+      !this.subagentGuard &&
+      !this.trustFile.yolo &&
+      hasDangerousCapability(tool)
+    ) {
+      permission = 'confirm';
+      source = 'default';
+    }
+
+    if (permission === 'confirm' && this.trustFile.yolo) {
+      // YOLO skips ALL confirm prompts (including destructive). Explicit deny
+      // rules above still block — YOLO never bypasses a user-configured denial.
+      permission = 'auto';
+      source = 'yolo';
+    }
+
+    return { permission, source, riskTier: tool.riskTier };
+  }
+
+  async trust(rule: TrustRule): Promise<void> {
+    this.trustFile.allow = addRule(this.trustFile.allow, rule);
+    await this.writeHome();
+    this.emitPersisted('allow', rule, 'trust');
+  }
+
+  async deny(rule: TrustRule): Promise<void> {
+    this.trustFile.deny = addRule(this.trustFile.deny, rule);
+    await this.writeHome();
+    this.emitPersisted('deny', rule, 'trust');
+  }
+
+  allowOnce(rule: TrustRule): void {
+    this.sessionAllow.add(ruleKey(rule));
+    this.emitPersisted('allow', rule, 'session');
+  }
+
+  denyOnce(rule: TrustRule): void {
+    this.sessionDeny.add(ruleKey(rule));
+    this.emitPersisted('deny', rule, 'session');
+  }
+
+  getYolo(): boolean {
+    return this.trustFile.yolo;
+  }
+
+  setYolo(v: boolean): void {
+    this.trustFile.yolo = v;
+  }
+
+  private emitPersisted(action: 'allow' | 'deny', rule: TrustRule, scope: 'session' | 'trust'): void {
+    this.events?.emit('permission.persisted', { action, tool: rule.tool, pattern: rule.pattern, scope });
+  }
+
+  private matchesSession(set: Set<string>, toolName: string, subject: string): boolean {
+    for (const key of set) {
+      const sep = key.indexOf('|');
+      const t = sep >= 0 ? key.slice(0, sep) : key;
+      const p = sep >= 0 ? key.slice(sep + 1) : '*';
+      if (matchesRule(t, p, toolName, subject)) return true;
+    }
+    return false;
+  }
+
+  private matchesRules(rules: readonly TrustRule[], toolName: string, subject: string): boolean {
+    return rules.some((r) => matchesRule(r.tool, r.pattern, toolName, subject));
+  }
+
+  private async readMerged(): Promise<TrustFile> {
+    const home = await this.readTrustFile(this.homeFile);
+    const project = await this.readTrustFile(this.projectFile);
+    // project appends; cannot weaken a home deny (deny always wins by being checked first)
+    return {
+      allow: [...home.allow, ...project.allow],
+      deny: [...home.deny, ...project.deny],
+      yolo: home.yolo || project.yolo,
+    };
+  }
+
+  private async readTrustFile(file: string): Promise<TrustFile> {
+    try {
+      const raw = await fsp.readFile(file, 'utf8');
+      const parsed = JSON.parse(raw) as Partial<TrustFile>;
+      return {
+        allow: Array.isArray(parsed.allow) ? parsed.allow : [],
+        deny: Array.isArray(parsed.deny) ? parsed.deny : [],
+        yolo: parsed.yolo === true,
+      };
+    } catch {
+      return { ...EMPTY_TRUST };
+    }
+  }
+
+  private async writeHome(): Promise<void> {
+    const dir = path.dirname(this.homeFile);
+    await fsp.mkdir(dir, { recursive: true });
+    const tmp = `${this.homeFile}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(this.stripProjectRules(this.trustFile), null, 2), 'utf8');
+    await restrictFilePermissions(tmp);
+    await fsp.rename(tmp, this.homeFile);
+  }
+
+  private stripProjectRules(t: TrustFile): TrustFile {
+    // home file stores only rules written via trust()/deny() (which always go to home);
+    // project rules are read-only and re-merged on load.
+    return t;
+  }
+}
+
+function extractSubject(tool: Tool, input: unknown): string {
+  if (!tool.subjectKey) return '';
+  const v = (input as Record<string, unknown> | null)?.[tool.subjectKey];
+  return typeof v === 'string' ? v : v === undefined ? '' : String(v);
+}
+
+function hasDangerousCapability(tool: Tool): boolean {
+  if (!tool.capabilities) return false;
+  return tool.capabilities.some((c) => DANGEROUS_CAPABILITIES.has(c));
+}
+
+function ruleKey(rule: TrustRule): string {
+  return `${rule.tool}|${rule.pattern}`;
+}
+
+function addRule(rules: readonly TrustRule[], rule: TrustRule): TrustRule[] {
+  if (rules.some((r) => r.tool === rule.tool && r.pattern === rule.pattern)) {
+    return [...rules];
+  }
+  return [...rules, rule];
+}
+
+function matchesRule(ruleTool: string, rulePattern: string, toolName: string, subject: string): boolean {
+  const toolOk = ruleTool === '*' || ruleTool === toolName;
+  if (!toolOk) return false;
+  if (rulePattern === '*') return true;
+  if (!subject) return false;
+  return matchGlob(rulePattern, subject);
+}
+
+export function matchGlob(pattern: string, subject: string): boolean {
+  const re = globToRegExp(pattern);
+  return re.test(subject);
+}
+
+function globToRegExp(pattern: string): RegExp {
+  let out = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i]!;
+    if (ch === '*' && pattern[i + 1] === '*') {
+      out += '.*';
+      i++;
+    } else if (ch === '*') {
+      out += '.*';
+    } else if (ch === '?') {
+      out += '.';
+    } else if (/[+^$.(){}|[\]\\]/.test(ch)) {
+      out += `\\${ch}`;
+    } else {
+      out += ch;
+    }
+  }
+  return new RegExp(`${out}$`, 's');
+}