Add files using upload-large-folder tool

packages/agent-core-v2/src/_base/contribution/registry.ts

@@ -0,0 +1,55 @@
+import { Disposable, type IDisposable } from '../di/lifecycle';
+import { Emitter, type Event } from '../event';
+
+export interface ContributionRegistration<T> {
+  readonly sourceId: string;
+  readonly priority: number;
+  readonly contribution: T;
+}
+
+export interface RegisterContributionOptions {
+  readonly priority?: number;
+}
+
+export class ContributionRegistry<T> extends Disposable {
+  private readonly registrations = new Map<string, ContributionRegistration<T>>();
+  private readonly onDidChangeEmitter = this._register(new Emitter<string>());
+  readonly onDidChange: Event<string> = this.onDidChangeEmitter.event;
+
+  register(
+    sourceId: string,
+    contribution: T,
+    options?: RegisterContributionOptions,
+  ): IDisposable {
+    const registration: ContributionRegistration<T> = {
+      sourceId,
+      priority: options?.priority ?? 0,
+      contribution,
+    };
+    this.registrations.set(sourceId, registration);
+    this.onDidChangeEmitter.fire(sourceId);
+    let active = true;
+    return {
+      dispose: () => {
+        if (!active) return;
+        active = false;
+        if (this.registrations.get(sourceId) !== registration) return;
+        this.registrations.delete(sourceId);
+        this.onDidChangeEmitter.fire(sourceId);
+      },
+    };
+  }
+
+  unregister(sourceId: string): void {
+    if (!this.registrations.delete(sourceId)) return;
+    this.onDidChangeEmitter.fire(sourceId);
+  }
+
+  entries(): readonly ContributionRegistration<T>[] {
+    return [...this.registrations.values()];
+  }
+
+  get(sourceId: string): ContributionRegistration<T> | undefined {
+    return this.registrations.get(sourceId);
+  }
+}

packages/agent-core-v2/src/_base/di/cascadeEngine.ts

@@ -0,0 +1,798 @@
+import { onUnexpectedError } from '../errors/unexpectedError';
+import { Emitter, type Event } from '../event';
+import { isPromiseLike } from '../lifecycle/disposer';
+import type { SyncDescriptor } from './descriptors';
+import {
+  PairIndex,
+  type DependencyGraph,
+  type ScopedToken,
+} from './dependencyGraph';
+import { CascadeConflictError } from './errors';
+import type { ServiceIdentifier } from './instantiation';
+
+export type UnitState = 'Pending' | 'Activating' | 'Active' | 'Unloading' | 'Failed';
+
+export type CascadeAction = 'provide' | 'unprovide' | 'update';
+
+export type UnitActivation = 'eager' | 'ondemand';
+
+export interface CascadeChange {
+  readonly action: CascadeAction;
+  readonly token: ServiceIdentifier<any>;
+  readonly descriptor?: SyncDescriptor<unknown>;
+  readonly instance?: unknown;
+  readonly activation?: UnitActivation;
+  readonly config?: unknown;
+  readonly reason: string;
+}
+
+export interface CascadeHistoryEntry {
+  readonly seq: number;
+  readonly reason: string;
+  readonly changes: ReadonlyArray<{ token: string; action: CascadeAction }>;
+  readonly affected: readonly string[];
+  readonly tornDown: readonly string[];
+  readonly rebuilt: readonly string[];
+  readonly failed: readonly string[];
+  readonly abortWaited: boolean;
+  readonly abortTimedOut: boolean;
+  readonly durationMs: number;
+}
+
+export interface UnitSnapshot {
+  readonly token: string;
+  readonly state: UnitState;
+  readonly error?: string;
+  readonly everActive: boolean;
+  readonly inFlight: boolean;
+}
+
+export interface UnitStateChange {
+  readonly token: string;
+  readonly state: UnitState;
+  readonly error?: string;
+}
+
+export interface CascadeEngineOptions {
+  onWillCascade?: (
+    affected: readonly ScopedToken[],
+    reason: string,
+  ) => void | Promise<void>;
+  readonly abortWaitMs?: number;
+  readonly resolveTimeoutMs?: number;
+  readonly historyCapacity?: number;
+  readonly now?: () => number;
+}
+
+export interface CascadeHost {
+  isRegistered(token: ServiceIdentifier<any>): boolean;
+  ownerScopeOf(token: ServiceIdentifier<any>): object | undefined;
+  isMaterialized(token: ServiceIdentifier<any>): boolean;
+  materialize(token: ServiceIdentifier<any>): unknown;
+  retire(token: ServiceIdentifier<any>): void | Promise<void>;
+  applyProvide(
+    token: ServiceIdentifier<any>,
+    descriptor: SyncDescriptor<unknown>,
+    config: unknown,
+  ): number;
+  applyProvideInstance(
+    token: ServiceIdentifier<any>,
+    instance: unknown,
+    config: unknown,
+  ): number;
+  applyUnprovide(token: ServiceIdentifier<any>): void;
+  recipeOf(token: ServiceIdentifier<any>): SyncDescriptor<unknown> | undefined;
+  dependenciesOf(
+    recipe: SyncDescriptor<unknown>,
+  ): Array<ServiceIdentifier<any>>;
+}
+
+export interface CascadeScopeHandle {
+  readonly cascade: CascadeEngine;
+  readonly cascadeDisposed: boolean;
+  readonly cascadeDepth: number;
+}
+
+interface UnitRecord {
+  state: UnitState;
+  error?: unknown;
+  activation: UnitActivation;
+  everActive: boolean;
+}
+
+interface QueuedRequest {
+  readonly engine: CascadeEngine;
+  readonly change: CascadeChange;
+  readonly resolve: () => void;
+  readonly reject: (error: unknown) => void;
+}
+
+const DEFAULT_ABORT_WAIT_MS = 5000;
+const DEFAULT_RESOLVE_TIMEOUT_MS = 30000;
+const DEFAULT_HISTORY_CAPACITY = 200;
+
+export class CascadeTree {
+  readonly graph: DependencyGraph;
+  readonly queue: QueuedRequest[] = [];
+  readonly engines = new Set<CascadeEngine>();
+  running = false;
+  orchestrator: object | undefined;
+  private readonly _inFlight = new PairIndex<true>();
+  private _settleWaiters: Array<() => void> = [];
+  private readonly _scopeSeq = new Map<object, number>();
+  private _nextScopeSeq = 0;
+  private readonly _droppedScopes = new WeakSet<object>();
+  private readonly _onDidAddEngine = new Emitter<CascadeEngine>();
+  readonly onDidAddEngine: Event<CascadeEngine> = this._onDidAddEngine.event;
+  private readonly _onDidRemoveEngine = new Emitter<CascadeEngine>();
+  readonly onDidRemoveEngine: Event<CascadeEngine> = this._onDidRemoveEngine.event;
+
+  constructor(graph: DependencyGraph) {
+    this.graph = graph;
+  }
+
+  addEngine(engine: CascadeEngine): void {
+    this.engines.add(engine);
+    this._onDidAddEngine.fire(engine);
+  }
+
+  removeEngine(engine: CascadeEngine): void {
+    if (this.engines.delete(engine)) {
+      this._onDidRemoveEngine.fire(engine);
+    }
+  }
+
+  inFlightSet(ref: ScopedToken, on: boolean): void {
+    if (on) {
+      this._inFlight.set(ref.scope, ref.token, true);
+    } else {
+      this._inFlight.delete(ref.scope, ref.token);
+    }
+  }
+
+  inFlightHas(ref: ScopedToken): boolean {
+    return this._inFlight.get(ref.scope, ref.token) !== undefined;
+  }
+
+  inFlightClear(refs: Iterable<ScopedToken>): void {
+    for (const ref of refs) {
+      this._inFlight.delete(ref.scope, ref.token);
+    }
+  }
+
+  seqOf(scope: object): number {
+    let seq = this._scopeSeq.get(scope);
+    if (seq === undefined) {
+      if (this._droppedScopes.has(scope)) {
+        return -1;
+      }
+      seq = this._nextScopeSeq++;
+      this._scopeSeq.set(scope, seq);
+    }
+    return seq;
+  }
+
+  dropScope(scope: object): void {
+    this._droppedScopes.add(scope);
+    this._scopeSeq.delete(scope);
+    this._inFlight.deleteScope(scope);
+  }
+
+  addSettleWaiter(waiter: () => void): void {
+    this._settleWaiters.push(waiter);
+  }
+
+  fireSettleWaiters(): void {
+    const waiters = this._settleWaiters.splice(0);
+    for (const waiter of waiters) {
+      waiter();
+    }
+  }
+}
+
+export class CascadeEngine {
+  private readonly _units = new Map<
+    ServiceIdentifier<any>,
+    UnitRecord
+  >();
+  private readonly _pendingIndex = new Map<
+    ServiceIdentifier<any>,
+    Set<ServiceIdentifier<any>>
+  >();
+  private readonly _history: CascadeHistoryEntry[] = [];
+  private _historySeq = 0;
+  private _disposed = false;
+  private _activationSuspended = 0;
+  private readonly _onDidChangeUnitState = new Emitter<UnitStateChange>();
+  readonly onDidChangeUnitState: Event<UnitStateChange> = this._onDidChangeUnitState.event;
+  private readonly _onDidCascade = new Emitter<CascadeHistoryEntry>();
+  readonly onDidCascade: Event<CascadeHistoryEntry> = this._onDidCascade.event;
+
+  constructor(
+    private readonly _host: CascadeHost,
+    private readonly _scope: CascadeScopeHandle,
+    private readonly _tree: CascadeTree,
+    private _options: CascadeEngineOptions = {},
+  ) {
+    this._tree.addEngine(this);
+  }
+
+  configure(options: CascadeEngineOptions): void {
+    this._options = { ...this._options, ...options };
+  }
+
+  stateOf(token: ServiceIdentifier<any>): UnitState | undefined {
+    return this._units.get(token)?.state;
+  }
+
+  activationOf(token: ServiceIdentifier<any>): UnitActivation | undefined {
+    return this._units.get(token)?.activation;
+  }
+
+  materializable(token: ServiceIdentifier<any>): boolean {
+    return this._host.recipeOf(token) !== undefined;
+  }
+
+  failureOf(token: ServiceIdentifier<any>): unknown {
+    const unit = this._units.get(token);
+    return unit?.state === 'Failed' ? unit.error : undefined;
+  }
+
+  isInFlight(token: ServiceIdentifier<any>): boolean {
+    const owner = this._host.ownerScopeOf(token) ?? this._scope;
+    return this._tree.inFlightHas({ scope: owner, token });
+  }
+
+  history(): readonly CascadeHistoryEntry[] {
+    return this._history;
+  }
+
+  pendingSnapshot(): ReadonlyMap<string, readonly string[]> {
+    const snapshot = new Map<string, readonly string[]>();
+    for (const [token, unit] of this._units) {
+      if (unit.state !== 'Pending') continue;
+      snapshot.set(
+        token.toString(),
+        this._missingDeps(token).map((dep) => dep.toString()),
+      );
+    }
+    return snapshot;
+  }
+
+  unitsSnapshot(): UnitSnapshot[] {
+    const snapshot: UnitSnapshot[] = [];
+    for (const [token, unit] of this._units) {
+      snapshot.push({
+        token: token.toString(),
+        state: unit.state,
+        error: unit.error === undefined ? undefined : serializeError(unit.error),
+        everActive: unit.everActive,
+        inFlight: this.isInFlight(token),
+      });
+    }
+    return snapshot;
+  }
+
+  submit(change: CascadeChange): Promise<void> {
+    if (this._disposed) {
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve, reject) => {
+      this._tree.queue.push({ engine: this, change, resolve, reject });
+      this._pump();
+    });
+  }
+
+  submitAll(changes: readonly CascadeChange[]): Promise<void> {
+    if (this._disposed || changes.length === 0) {
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve, reject) => {
+      for (const change of changes) {
+        this._tree.queue.push({ engine: this, change, resolve, reject });
+      }
+      this._pump();
+    });
+  }
+
+  update(token: ServiceIdentifier<any>, reason?: string): Promise<void> {
+    return this.submit({
+      action: 'update',
+      token,
+      reason: reason ?? `update ${String(token)}`,
+    });
+  }
+
+  whenIdle(): Promise<void> {
+    if (!this._tree.running && this._tree.queue.length === 0) {
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      this._tree.addSettleWaiter(() => {
+        void this.whenIdle().then(resolve);
+      });
+    });
+  }
+
+  suspendActivation(): void {
+    this._activationSuspended++;
+  }
+
+  resumeActivation(): void {
+    if (this._activationSuspended === 0) {
+      return;
+    }
+    this._activationSuspended--;
+    if (this._activationSuspended > 0 || this._disposed) {
+      return;
+    }
+    const rebuilt: string[] = [];
+    const failed: string[] = [];
+    this._recheckTreeFixpoint(rebuilt, failed);
+  }
+
+  private _recheckTreeFixpoint(rebuilt: string[], failed: string[]): void {
+    const enginesInOrder = [...this._tree.engines]
+      .filter((engine) => !engine._disposed)
+      .toSorted((a, b) => a._scope.cascadeDepth - b._scope.cascadeDepth);
+    for (;;) {
+      let progress = false;
+      for (const engine of enginesInOrder) {
+        const before = rebuilt.length + failed.length;
+        engine._recheckForCascade(rebuilt, failed);
+        if (rebuilt.length + failed.length > before) {
+          progress = true;
+        }
+      }
+      if (!progress) {
+        break;
+      }
+    }
+  }
+
+  resolveWhenAvailable<T>(
+    token: ServiceIdentifier<any>,
+    timeoutMs?: number,
+  ): Promise<T> {
+    if (!this.isInFlight(token)) {
+      try {
+        return Promise.resolve(this._host.materialize(token) as T);
+      } catch (error) {
+        return Promise.reject(error);
+      }
+    }
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(
+          new CascadeConflictError(
+            String(token),
+            'timed out waiting for the in-flight cascade to settle',
+          ),
+        );
+      }, timeoutMs ?? this._options.resolveTimeoutMs ?? DEFAULT_RESOLVE_TIMEOUT_MS);
+      this._tree.addSettleWaiter(() => {
+        clearTimeout(timer);
+        try {
+          resolve(this._host.materialize(token) as T);
+        } catch (error) {
+          reject(error);
+        }
+      });
+    });
+  }
+
+  observedMaterialization(token: ServiceIdentifier<any>): void {
+    const unit = this._units.get(token);
+    if (unit !== undefined && unit.state === 'Pending') {
+      unit.everActive = true;
+      this._setUnitState(token, unit, 'Active', undefined);
+    }
+  }
+
+  dispose(): void {
+    this._disposed = true;
+    this._tree.removeEngine(this);
+    this._tree.dropScope(this._scope);
+    this._units.clear();
+    this._pendingIndex.clear();
+    const remaining: QueuedRequest[] = [];
+    for (const request of this._tree.queue) {
+      if (request.engine === this) {
+        request.resolve();
+      } else {
+        remaining.push(request);
+      }
+    }
+    this._tree.queue.length = 0;
+    this._tree.queue.push(...remaining);
+    this._onDidChangeUnitState.dispose();
+    this._onDidCascade.dispose();
+  }
+
+  _teardownForCascade(
+    token: ServiceIdentifier<any>,
+    tornDown: string[],
+    parkAsPending: boolean,
+  ): void | Promise<void> {
+    if (this._disposed || !this._host.isMaterialized(token)) {
+      return undefined;
+    }
+    this._setUnitState(token, this._unitFor(token), 'Unloading', undefined);
+    const out = this._host.retire(token);
+    tornDown.push(this._label({ scope: this._scope, token }));
+    if (parkAsPending) {
+      this._markPending(token, undefined, true);
+    }
+    return out;
+  }
+
+  _recheckForCascade(rebuilt: string[], failed: string[]): void {
+    if (this._disposed || this._activationSuspended > 0) {
+      return;
+    }
+    this._recheckPending(rebuilt, failed);
+  }
+
+  _applyChangeForCascade(change: CascadeChange): void {
+    if (this._disposed) {
+      return;
+    }
+    switch (change.action) {
+      case 'provide':
+        if (change.descriptor !== undefined) {
+          this._host.applyProvide(change.token, change.descriptor, change.config);
+          this._markPending(change.token, change.activation ?? 'eager', false);
+        } else {
+          this._host.applyProvideInstance(change.token, change.instance, change.config);
+          const unit = this._unitFor(change.token);
+          unit.everActive = true;
+          this._setUnitState(change.token, unit, 'Active', undefined);
+        }
+        break;
+      case 'unprovide':
+        this._host.applyUnprovide(change.token);
+        this._units.delete(change.token);
+        break;
+      case 'update':
+        this._markPending(change.token, undefined, true);
+        break;
+    }
+  }
+
+  private _pump(): void {
+    if (this._tree.running) {
+      return;
+    }
+    const batch = this._tree.queue.splice(0);
+    if (batch.length === 0) {
+      return;
+    }
+    this._tree.running = true;
+    const finish = (error?: unknown): void => {
+      this._tree.running = false;
+      for (const request of batch) {
+        if (error === undefined) {
+          request.resolve();
+        } else {
+          request.reject(error);
+        }
+      }
+      this._tree.fireSettleWaiters();
+      this._pump();
+    };
+    const orchestrator = batch[0]!.engine;
+    try {
+      const out = orchestrator._transact(batch);
+      if (isPromiseLike(out)) {
+        Promise.resolve(out).then(
+          () => { finish(); },
+          (error: unknown) => { finish(error); },
+        );
+      } else {
+        finish();
+      }
+    } catch (error) {
+      finish(error);
+    }
+  }
+
+  private _transact(batch: QueuedRequest[]): void | Promise<void> {
+    const changes = mergeBatch(batch);
+    const started = this._options.now?.() ?? Date.now();
+    const reason = changes.map(({ change }) => change.reason).join('; ');
+    const affected = this._tree.graph.affectedSet(
+      changes.map(({ engine, change }) => ({ scope: engine._scope, token: change.token })),
+    );
+    for (const ref of affected) {
+      this._tree.inFlightSet(ref, true);
+    }
+    this._tree.orchestrator = this._scope;
+    const complete = (abort: { waited: boolean; timedOut: boolean }): void | Promise<void> => {
+      const clear = (): void => {
+        this._tree.inFlightClear(affected);
+        this._tree.orchestrator = undefined;
+      };
+      let out: void | Promise<void>;
+      try {
+        out = this._applyTransaction(changes, affected, reason, started, abort);
+      } catch (error) {
+        clear();
+        throw error;
+      }
+      if (isPromiseLike(out)) {
+        return Promise.resolve(out).then(clear, (error: unknown) => {
+          clear();
+          throw error;
+        });
+      }
+      clear();
+      return undefined;
+    };
+    const wait = this._waitForAbort(affected, reason);
+    if (isPromiseLike(wait)) {
+      return Promise.resolve(wait).then(complete);
+    }
+    return complete(wait);
+  }
+
+  private _waitForAbort(
+    affected: readonly ScopedToken[],
+    reason: string,
+  ): { waited: boolean; timedOut: boolean } | Promise<{ waited: boolean; timedOut: boolean }> {
+    const hook = this._options.onWillCascade;
+    if (hook === undefined) {
+      return { waited: false, timedOut: false };
+    }
+    let out: void | Promise<void>;
+    try {
+      out = hook(affected, reason);
+    } catch (error) {
+      onUnexpectedError(error);
+      return { waited: false, timedOut: false };
+    }
+    if (!isPromiseLike(out)) {
+      return { waited: false, timedOut: false };
+    }
+    const waitMs = this._options.abortWaitMs ?? DEFAULT_ABORT_WAIT_MS;
+    return Promise.race([
+      Promise.resolve(out).then(
+        () => ({ waited: true, timedOut: false }),
+        (error: unknown) => {
+          onUnexpectedError(error);
+          return { waited: true, timedOut: false };
+        },
+      ),
+      new Promise<{ waited: boolean; timedOut: boolean }>((resolve) => {
+        setTimeout(() => { resolve({ waited: true, timedOut: true }); }, waitMs);
+      }),
+    ]);
+  }
+
+  private _applyTransaction(
+    changes: QueuedRequest[],
+    affected: readonly ScopedToken[],
+    reason: string,
+    started: number,
+    abort: { waited: boolean; timedOut: boolean },
+  ): void | Promise<void> {
+    const tornDown: string[] = [];
+    const rebuilt: string[] = [];
+    const failed: string[] = [];
+
+    const teardownOrder = this._tree.graph.reverseTopoOrder(affected);
+    let index = 0;
+    const step = (): void | Promise<void> => {
+      while (index < teardownOrder.length) {
+        const ref = teardownOrder[index]!;
+        index += 1;
+        const owner = engineOf(ref);
+        if (owner === undefined || owner._disposed) {
+          continue;
+        }
+        const removed = changes.some(
+          ({ engine, change }) =>
+            engine === owner && change.token === ref.token && change.action === 'unprovide',
+        );
+        const out = owner._teardownForCascade(ref.token, tornDown, !removed);
+        if (isPromiseLike(out)) {
+          return Promise.resolve(out).then(step);
+        }
+      }
+      return undefined;
+    };
+
+    const after = (): void => {
+      for (const { engine, change } of changes) {
+        engine._applyChangeForCascade(change);
+      }
+      this._recheckTreeFixpoint(rebuilt, failed);
+      this._pushHistory({
+        seq: ++this._historySeq,
+        reason,
+        changes: changes.map(({ engine, change }) => ({
+          token: this._label({ scope: engine._scope, token: change.token }),
+          action: change.action,
+        })),
+        affected: affected.map((ref) => this._label(ref)),
+        tornDown,
+        rebuilt,
+        failed,
+        abortWaited: abort.waited,
+        abortTimedOut: abort.timedOut,
+        durationMs: (this._options.now?.() ?? Date.now()) - started,
+      });
+    };
+
+    const drained = step();
+    if (isPromiseLike(drained)) {
+      return Promise.resolve(drained).then(after);
+    }
+    after();
+    return undefined;
+  }
+
+  private _unitFor(token: ServiceIdentifier<any>): UnitRecord {
+    let unit = this._units.get(token);
+    if (unit === undefined) {
+      unit = { state: 'Pending', activation: 'eager', everActive: false };
+      this._units.set(token, unit);
+      this._onDidChangeUnitState.fire({ token: token.toString(), state: 'Pending' });
+    }
+    return unit;
+  }
+
+  private _setUnitState(
+    token: ServiceIdentifier<any>,
+    unit: UnitRecord,
+    state: UnitState,
+    error: unknown,
+  ): void {
+    const changed = unit.state !== state;
+    unit.state = state;
+    unit.error = error;
+    if (changed) {
+      this._onDidChangeUnitState.fire({
+        token: token.toString(),
+        state,
+        error: error === undefined ? undefined : serializeError(error),
+      });
+    }
+  }
+
+  private _markPending(
+    token: ServiceIdentifier<any>,
+    activation?: UnitActivation,
+    everActive?: boolean,
+  ): void {
+    const unit = this._unitFor(token);
+    this._setUnitState(token, unit, 'Pending', undefined);
+    if (activation !== undefined) {
+      unit.activation = activation;
+    }
+    if (everActive !== undefined) {
+      unit.everActive = everActive;
+    }
+  }
+
+  private _recheckPending(rebuilt: string[], failed: string[]): void {
+    for (;;) {
+      this._pendingIndex.clear();
+      const satisfied: ServiceIdentifier<any>[] = [];
+      for (const [token, unit] of this._units) {
+        if (unit.state !== 'Pending') continue;
+        const missing = this._missingDeps(token);
+        if (missing.length === 0) {
+          if (unit.everActive || unit.activation === 'eager') {
+            satisfied.push(token);
+          }
+        } else {
+          for (const dep of missing) {
+            let waiters = this._pendingIndex.get(dep);
+            if (waiters === undefined) {
+              waiters = new Set();
+              this._pendingIndex.set(dep, waiters);
+            }
+            waiters.add(token);
+          }
+        }
+      }
+      if (satisfied.length === 0) {
+        return;
+      }
+      const ordered = this._tree.graph.topoOrder(
+        satisfied.map((token) => ({ scope: this._scope, token })),
+      );
+      for (const ref of ordered) {
+        this._activate(ref.token, rebuilt, failed);
+      }
+      for (const [token, unit] of this._units) {
+        if (
+          (unit.state === 'Pending' || unit.state === 'Activating') &&
+          this._host.isMaterialized(token)
+        ) {
+          unit.everActive = true;
+          this._setUnitState(token, unit, 'Active', undefined);
+        }
+      }
+    }
+  }
+
+  private _activate(token: ServiceIdentifier<any>, rebuilt: string[], failed: string[]): void {
+    const unit = this._unitFor(token);
+    this._setUnitState(token, unit, 'Activating', undefined);
+    try {
+      this._host.materialize(token);
+      unit.everActive = true;
+      this._setUnitState(token, unit, 'Active', undefined);
+      rebuilt.push(this._label({ scope: this._scope, token }));
+    } catch (error) {
+      this._setUnitState(token, unit, 'Failed', error);
+      failed.push(this._label({ scope: this._scope, token }));
+    }
+  }
+
+  private _missingDeps(token: ServiceIdentifier<any>): Array<ServiceIdentifier<any>> {
+    const recipe = this._host.recipeOf(token);
+    if (recipe === undefined) {
+      return [token];
+    }
+    return this._host
+      .dependenciesOf(recipe)
+      .filter((dep) => !this._isAvailable(dep));
+  }
+
+  private _isAvailable(dep: ServiceIdentifier<any>): boolean {
+    if (!this._host.isRegistered(dep)) {
+      return false;
+    }
+    const owner = this._host.ownerScopeOf(dep);
+    const engine = owner === undefined ? undefined : engineOf({ scope: owner, token: dep });
+    const state = engine?.stateOf(dep);
+    if (state === undefined || state === 'Active') {
+      return true;
+    }
+    return (
+      state === 'Pending' &&
+      engine !== undefined &&
+      engine.activationOf(dep) === 'ondemand' &&
+      engine.materializable(dep)
+    );
+  }
+
+  private _label(ref: ScopedToken): string {
+    if (ref.scope === this._tree.orchestrator) {
+      return ref.token.toString();
+    }
+    return `#${this._tree.seqOf(ref.scope)}:${ref.token.toString()}`;
+  }
+
+  _mergeKey(): string {
+    return String(this._tree.seqOf(this._scope));
+  }
+
+  private _pushHistory(entry: CascadeHistoryEntry): void {
+    this._history.push(entry);
+    const capacity = this._options.historyCapacity ?? DEFAULT_HISTORY_CAPACITY;
+    if (this._history.length > capacity) {
+      this._history.splice(0, this._history.length - capacity);
+    }
+    this._onDidCascade.fire(entry);
+  }
+}
+
+function serializeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function engineOf(ref: ScopedToken): CascadeEngine | undefined {
+  return (ref.scope as Partial<CascadeScopeHandle>).cascade;
+}
+
+function mergeBatch(batch: QueuedRequest[]): QueuedRequest[] {
+  const byKey = new Map<string, QueuedRequest>();
+  for (const request of batch) {
+    const key = `${request.engine._mergeKey()}:${request.change.token.toString()}`;
+    byKey.set(key, request);
+  }
+  return [...byKey.values()];
+}

packages/agent-core-v2/src/_base/di/collection.ts

@@ -0,0 +1,302 @@
+import { Emitter, type Event } from '../event';
+import type { Ledger } from '../lifecycle/ledger';
+import { storeCustomDependency, type ServiceIdentifier } from './instantiation';
+
+export interface CollectionToken<T> {
+  (target: any, key: string | symbol | undefined, index: number): void;
+
+  readonly name: string;
+
+  readonly __t?: T;
+
+  toString(): string;
+}
+
+export interface DefinitionToken<T> extends CollectionToken<T> {
+  readonly __definition?: T;
+}
+
+export interface DefinitionRecord<T> {
+  readonly definition: T;
+  readonly owner: string;
+  readonly generation: number;
+}
+
+export interface DefinitionChange<T> {
+  readonly current: DefinitionRecord<T> | undefined;
+  readonly previous: DefinitionRecord<T> | undefined;
+}
+
+export interface DefinitionView<T> {
+  readonly current: DefinitionRecord<T> | undefined;
+  readonly onDidChangeDefinition: Event<DefinitionChange<T>>;
+}
+
+const _collectionTokens = new Map<string, CollectionToken<unknown>>();
+const _collectionTokenSet = new WeakSet<object>();
+const _definitionTokenSet = new WeakSet<object>();
+const _collectionValidators = new WeakMap<
+  object,
+  (value: unknown, existing: readonly unknown[]) => void
+>();
+
+export function collection<T>(
+  name: string,
+  options: { readonly validate?: (value: T, existing: readonly T[]) => void } = {},
+): CollectionToken<T> {
+  const existing = _collectionTokens.get(name);
+  if (existing !== undefined) {
+    return existing as CollectionToken<T>;
+  }
+  const token = function collectionDecorator(
+    target: any,
+    _key: string | symbol | undefined,
+    index: number,
+  ): void {
+    if (arguments.length !== 3) {
+      throw new Error('@CollectionToken-decorator can only be used to decorate a parameter');
+    }
+    storeCustomDependency(token as unknown as ServiceIdentifier<any>, 'collection', target, index);
+  } as unknown as CollectionToken<T>;
+  Object.defineProperty(token, 'toString', {
+    value: () => `collection:${name}`,
+    enumerable: false,
+  });
+  Object.defineProperty(token, 'name', { value: name, enumerable: false, configurable: true });
+  _collectionTokens.set(name, token as CollectionToken<unknown>);
+  _collectionTokenSet.add(token);
+  if (options.validate !== undefined) {
+    _collectionValidators.set(
+      token,
+      options.validate as (value: unknown, existing: readonly unknown[]) => void,
+    );
+  }
+  return token;
+}
+
+export function definition<T>(name: string): DefinitionToken<T> {
+  const token = collection<T>(name, {
+    validate: (_value, existing) => {
+      if (existing.length > 0) throw new Error(`Definition ${name} already has an active provider`);
+    },
+  }) as DefinitionToken<T>;
+  _definitionTokenSet.add(token);
+  return token;
+}
+
+export function isCollectionToken(thing: unknown): thing is CollectionToken<unknown> {
+  return typeof thing === 'function' && _collectionTokenSet.has(thing);
+}
+
+export function isDefinitionToken(thing: unknown): thing is DefinitionToken<unknown> {
+  return typeof thing === 'function' && _definitionTokenSet.has(thing);
+}
+
+export interface CollectionRecord<T> {
+  readonly value: T;
+  readonly providerName: string;
+  readonly scopePath: string;
+}
+
+export interface CollectionChange<T> {
+  readonly added: readonly T[];
+  readonly removed: readonly T[];
+}
+
+export interface CollectionView<T> {
+  readonly items: readonly T[];
+  readonly records: readonly CollectionRecord<T>[];
+  readonly onDidChange: Event<CollectionChange<T>>;
+}
+
+interface StoredRecord {
+  readonly id: number;
+  readonly value: unknown;
+  readonly providerName: string;
+  readonly scopePath: string;
+  readonly provider: object;
+  readonly providerBook: Ledger;
+}
+
+export type { StoredRecord };
+
+export class CollectionStore {
+  private readonly _records = new Map<
+    CollectionToken<unknown>,
+    Map<number, StoredRecord>
+  >();
+  private readonly _views = new Set<CollectionViewImpl<unknown>>();
+  private _nextId = 0;
+
+  constructor(private readonly _parentOf: (container: object) => object | undefined) {}
+
+  addRecord<T>(
+    token: CollectionToken<T>,
+    provider: object,
+    providerName: string,
+    scopePath: string,
+    providerBook: Ledger,
+    value: T,
+  ): () => void {
+    let records = this._records.get(token as CollectionToken<unknown>);
+    if (records === undefined) {
+      records = new Map();
+      this._records.set(token as CollectionToken<unknown>, records);
+    }
+    _collectionValidators.get(token)?.(
+      value,
+      [...records.values()].map((entry) => entry.value),
+    );
+    const record: StoredRecord = {
+      id: ++this._nextId,
+      value,
+      providerName,
+      scopePath,
+      provider,
+      providerBook,
+    };
+    records.set(record.id, record);
+    const fire = (view: CollectionViewImpl<unknown>, kind: 'added' | 'removed'): void => {
+      if (view.consumer === provider || this._isRelated(view.consumer, provider)) {
+        view._fireDelta(kind, [record]);
+      }
+    };
+    for (const view of this._views) {
+      if (view.token === (token as unknown as CollectionToken<unknown>)) {
+        fire(view, 'added');
+      }
+    }
+    return () => {
+      if (!records.delete(record.id)) {
+        return;
+      }
+      for (const view of this._views) {
+        if (view.token === (token as unknown as CollectionToken<unknown>)) {
+          fire(view, 'removed');
+        }
+      }
+    };
+  }
+
+  createView<T>(token: CollectionToken<T>, consumer: object): CollectionViewImpl<T> {
+    const view = new CollectionViewImpl<T>(this, token, consumer);
+    this._views.add(view as unknown as CollectionViewImpl<unknown>);
+    return view;
+  }
+
+  dropView(view: CollectionViewImpl<unknown>): void {
+    this._views.delete(view);
+  }
+
+  recordsFor<T>(token: CollectionToken<T>, consumer: object): CollectionRecord<T>[] {
+    const records = this._records.get(token as CollectionToken<unknown>);
+    if (records === undefined) {
+      return [];
+    }
+    const out: CollectionRecord<T>[] = [];
+    for (const record of records.values()) {
+      if (record.provider === consumer || this._isRelated(consumer, record.provider)) {
+        out.push({
+          value: record.value as T,
+          providerName: record.providerName,
+          scopePath: record.scopePath,
+        });
+      }
+    }
+    return out;
+  }
+
+  storedRecordsFor(
+    token: CollectionToken<unknown>,
+    consumer: object,
+  ): readonly StoredRecord[] {
+    const records = this._records.get(token);
+    if (records === undefined) {
+      return [];
+    }
+    const out: StoredRecord[] = [];
+    for (const record of records.values()) {
+      if (record.provider === consumer || this._isRelated(consumer, record.provider)) {
+        out.push(record);
+      }
+    }
+    return out;
+  }
+
+  definitionFor<T>(token: CollectionToken<T>, consumer: object): DefinitionRecord<T> | undefined {
+    const record = this.storedRecordsFor(
+      token as CollectionToken<unknown>,
+      consumer,
+    )[0];
+    if (record === undefined) return undefined;
+    return {
+      definition: record.value as T,
+      owner: `${record.providerName}@${record.scopePath}`,
+      generation: record.id,
+    };
+  }
+
+  private _isRelated(consumer: object, provider: object): boolean {
+    for (let c: object | undefined = consumer; c !== undefined; c = this._parentOf(c)) {
+      if (c === provider) return true;
+    }
+    for (let p: object | undefined = provider; p !== undefined; p = this._parentOf(p)) {
+      if (p === consumer) return true;
+    }
+    return false;
+  }
+}
+
+export class CollectionViewImpl<T> implements CollectionView<T>, DefinitionView<T> {
+  private readonly _onDidChange = new Emitter<CollectionChange<T>>();
+  private readonly _onDidChangeDefinition = new Emitter<DefinitionChange<T>>();
+  readonly onDidChange: Event<CollectionChange<T>> = this._onDidChange.event;
+  readonly onDidChangeDefinition: Event<DefinitionChange<T>> =
+    this._onDidChangeDefinition.event;
+
+  constructor(
+    private readonly _store: CollectionStore,
+    readonly token: CollectionToken<T>,
+    readonly consumer: object,
+  ) {}
+
+  get records(): CollectionRecord<T>[] {
+    return this._store.recordsFor(this.token, this.consumer);
+  }
+
+  get items(): readonly T[] {
+    return this.records.map((record) => record.value);
+  }
+
+  get current(): DefinitionRecord<T> | undefined {
+    return this._store.definitionFor(this.token, this.consumer);
+  }
+
+  _fireDelta(kind: 'added' | 'removed', records: readonly StoredRecord[]): void {
+    const previous = kind === 'removed' ? this.definitionRecord(records[0]) : undefined;
+    const values = records.map((record) => record.value as T);
+    this._onDidChange.fire(
+      kind === 'added'
+        ? { added: values, removed: [] }
+        : { added: [], removed: values },
+    );
+    if (isDefinitionToken(this.token)) {
+      this._onDidChangeDefinition.fire({ current: this.current, previous });
+    }
+  }
+
+  dispose(): void {
+    this._store.dropView(this as unknown as CollectionViewImpl<unknown>);
+    this._onDidChange.dispose();
+    this._onDidChangeDefinition.dispose();
+  }
+
+  private definitionRecord(record: StoredRecord | undefined): DefinitionRecord<T> | undefined {
+    if (record === undefined) return undefined;
+    return {
+      definition: record.value as T,
+      owner: `${record.providerName}@${record.scopePath}`,
+      generation: record.id,
+    };
+  }
+}

packages/agent-core-v2/src/_base/di/dependencyGraph.ts

@@ -0,0 +1,262 @@
+import type { ServiceIdentifier } from './instantiation';
+
+export interface ScopedToken {
+  readonly scope: object;
+  readonly token: ServiceIdentifier<any>;
+}
+
+export type DependencyEdgeKind = 'instance' | 'collection';
+
+export interface DependencyEdge {
+  readonly consumer: ScopedToken;
+  readonly dependency: ScopedToken;
+  readonly kind: DependencyEdgeKind;
+}
+
+export class PairIndex<V> {
+  private readonly _map = new Map<object, Map<
+    ServiceIdentifier<any>,
+    V
+  >>();
+
+  get(scope: object, token: ServiceIdentifier<unknown>): V | undefined {
+    return this._map.get(scope)?.get(token);
+  }
+
+  set(scope: object, token: ServiceIdentifier<unknown>, value: V): void {
+    let inner = this._map.get(scope);
+    if (inner === undefined) {
+      inner = new Map();
+      this._map.set(scope, inner);
+    }
+    inner.set(token, value);
+  }
+
+  delete(scope: object, token: ServiceIdentifier<unknown>): void {
+    const inner = this._map.get(scope);
+    if (inner === undefined) return;
+    inner.delete(token);
+    if (inner.size === 0) {
+      this._map.delete(scope);
+    }
+  }
+
+  deleteScope(scope: object): void {
+    this._map.delete(scope);
+  }
+
+  get size(): number {
+    return this._map.size;
+  }
+
+  entries(): Array<[ScopedToken, V]> {
+    const out: Array<[ScopedToken, V]> = [];
+    for (const [scope, inner] of this._map) {
+      for (const [token, value] of inner) {
+        out.push([{ scope, token }, value]);
+      }
+    }
+    return out;
+  }
+
+  clear(): void {
+    this._map.clear();
+  }
+}
+
+export class DependencyGraph {
+  private readonly _refByInstance = new Map<object, ScopedToken>();
+  private readonly _instanceByRef = new PairIndex<object>();
+  private readonly _out = new Map<object, PairIndex<DependencyEdgeKind>>();
+  private readonly _in = new PairIndex<Map<object, DependencyEdgeKind>>();
+
+  addInstance(
+    instance: object,
+    scope: object,
+    token: ServiceIdentifier<any>,
+  ): void {
+    const ref: ScopedToken = { scope, token };
+    this._refByInstance.set(instance, ref);
+    this._instanceByRef.set(scope, token, instance);
+  }
+
+  removeInstance(instance: object): void {
+    const ref = this._refByInstance.get(instance);
+    if (ref !== undefined) {
+      this._refByInstance.delete(instance);
+      if (this._instanceByRef.get(ref.scope, ref.token) === instance) {
+        this._instanceByRef.delete(ref.scope, ref.token);
+      }
+    }
+    const out = this._out.get(instance);
+    if (out !== undefined) {
+      for (const [dependency] of out.entries()) {
+        const inbound = this._in.get(dependency.scope, dependency.token);
+        if (inbound !== undefined) {
+          inbound.delete(instance);
+          if (inbound.size === 0) {
+            this._in.delete(dependency.scope, dependency.token);
+          }
+        }
+      }
+      this._out.delete(instance);
+    }
+  }
+
+  removeScope(scope: object): void {
+    for (const [instance, ref] of this._refByInstance) {
+      if (ref.scope === scope) {
+        this.removeInstance(instance);
+      }
+    }
+    this._instanceByRef.deleteScope(scope);
+    this._in.deleteScope(scope);
+    for (const [instance, out] of this._out) {
+      out.deleteScope(scope);
+      if (out.size === 0) {
+        this._out.delete(instance);
+      }
+    }
+  }
+
+  addEdge(
+    consumerInstance: object,
+    dependency: ScopedToken,
+    kind: DependencyEdgeKind = 'instance',
+  ): void {
+    let out = this._out.get(consumerInstance);
+    if (out === undefined) {
+      out = new PairIndex();
+      this._out.set(consumerInstance, out);
+    }
+    out.set(dependency.scope, dependency.token, kind);
+
+    let inbound = this._in.get(dependency.scope, dependency.token);
+    if (inbound === undefined) {
+      inbound = new Map();
+      this._in.set(dependency.scope, dependency.token, inbound);
+    }
+    inbound.set(consumerInstance, kind);
+  }
+
+  affectedSet(changed: Iterable<ScopedToken>): ScopedToken[] {
+    const seen = new PairIndex<true>();
+    const queue: ScopedToken[] = [];
+    const push = (ref: ScopedToken): void => {
+      if (seen.get(ref.scope, ref.token) !== undefined) return;
+      seen.set(ref.scope, ref.token, true);
+      queue.push(ref);
+    };
+    for (const ref of changed) {
+      push(ref);
+    }
+    const affected: ScopedToken[] = [];
+    while (queue.length > 0) {
+      const ref = queue.pop()!;
+      affected.push(ref);
+      const inbound = this._in.get(ref.scope, ref.token);
+      if (inbound === undefined) continue;
+      for (const [consumerInstance, kind] of inbound) {
+        if (kind !== 'instance') continue;
+        const consumer = this._refByInstance.get(consumerInstance);
+        if (consumer === undefined) continue;
+        push(consumer);
+      }
+    }
+    return affected;
+  }
+
+  topoOrder(tokens: Iterable<ScopedToken>): ScopedToken[] {
+    const subset = new PairIndex<ScopedToken>();
+    for (const ref of tokens) {
+      subset.set(ref.scope, ref.token, ref);
+    }
+    const ordered: ScopedToken[] = [];
+    const done = new PairIndex<true>();
+    const visit = (ref: ScopedToken): void => {
+      if (done.get(ref.scope, ref.token) !== undefined) return;
+      done.set(ref.scope, ref.token, true);
+      for (const dependency of this._dependenciesOf(ref, subset)) {
+        visit(dependency);
+      }
+      ordered.push(ref);
+    };
+    for (const [, ref] of subset.entries()) {
+      visit(ref);
+    }
+    return ordered;
+  }
+
+  reverseTopoOrder(tokens: Iterable<ScopedToken>): ScopedToken[] {
+    return this.topoOrder(tokens).toReversed();
+  }
+
+  findCycle(label: (ref: ScopedToken) => string): string[] | null {
+    const state = new PairIndex<'visiting' | 'done'>();
+    const path: ScopedToken[] = [];
+    const visit = (ref: ScopedToken): string[] | null => {
+      state.set(ref.scope, ref.token, 'visiting');
+      path.push(ref);
+      for (const dependency of this._dependenciesOf(ref, undefined)) {
+        const mark = state.get(dependency.scope, dependency.token);
+        if (mark === 'done') continue;
+        if (mark === 'visiting') {
+          const start = path.findIndex(
+            (entry) =>
+              entry.scope === dependency.scope && entry.token === dependency.token,
+          );
+          return [...path.slice(start), dependency].map(label);
+        }
+        const cycle = visit(dependency);
+        if (cycle !== null) return cycle;
+      }
+      path.pop();
+      state.set(ref.scope, ref.token, 'done');
+      return null;
+    };
+    for (const [ref] of this._instanceByRef.entries()) {
+      if (state.get(ref.scope, ref.token) !== undefined) continue;
+      const cycle = visit(ref);
+      if (cycle !== null) return cycle;
+    }
+    return null;
+  }
+
+  edges(): DependencyEdge[] {
+    const edges: DependencyEdge[] = [];
+    for (const [consumerInstance, out] of this._out) {
+      const consumer = this._refByInstance.get(consumerInstance);
+      if (consumer === undefined) continue;
+      for (const [dependency, kind] of out.entries()) {
+        edges.push({ consumer, dependency, kind });
+      }
+    }
+    return edges;
+  }
+
+  clear(): void {
+    this._refByInstance.clear();
+    this._instanceByRef.clear();
+    this._out.clear();
+    this._in.clear();
+  }
+
+  private _dependenciesOf(
+    ref: ScopedToken,
+    subset: PairIndex<ScopedToken> | undefined,
+  ): ScopedToken[] {
+    const instance = this._instanceByRef.get(ref.scope, ref.token);
+    if (instance === undefined) return [];
+    const out = this._out.get(instance);
+    if (out === undefined) return [];
+    const result: ScopedToken[] = [];
+    for (const [dependency, kind] of out.entries()) {
+      if (kind !== 'instance') continue;
+      if (subset !== undefined && subset.get(dependency.scope, dependency.token) === undefined) {
+        continue;
+      }
+      result.push(dependency);
+    }
+    return result;
+  }
+}

packages/agent-core-v2/src/_base/di/descriptors.ts

@@ -0,0 +1,14 @@
+export class SyncDescriptor<T> {
+  public readonly ctor: any;
+
+  constructor(
+    ctor: new (...args: any[]) => T,
+    public readonly staticArguments: ReadonlyArray<any> = [],
+  ) {
+    this.ctor = ctor;
+  }
+}
+
+export interface SyncDescriptor0<T> {
+  readonly ctor: new () => T;
+}

packages/agent-core-v2/src/_base/di/errors.ts

@@ -0,0 +1,30 @@
+import type { Graph } from './graph';
+
+export class CyclicDependencyError extends Error {
+  readonly path: ReadonlyArray<string>;
+
+  constructor(pathOrGraph: ReadonlyArray<string> | Graph<any>) {
+    if (Array.isArray(pathOrGraph)) {
+      const path = pathOrGraph as ReadonlyArray<string>;
+      super(`Cyclic DI dependency detected: ${path.join(' → ')}`);
+      this.path = path;
+    } else {
+      const graph = pathOrGraph as Graph<any>;
+      const cycle = graph.findCycleSlow();
+      const detail = cycle ?? `UNABLE to detect cycle, dumping graph:\n${graph.toString()}`;
+      super(`cyclic dependency between services: ${detail}`);
+      this.path = cycle ? cycle.split(' -> ') : [];
+    }
+    this.name = 'CyclicDependencyError';
+  }
+}
+
+export class CascadeConflictError extends Error {
+  constructor(
+    readonly token: string,
+    readonly detail: string,
+  ) {
+    super(`Cascade conflict resolving '${token}': ${detail}`);
+    this.name = 'CascadeConflictError';
+  }
+}

packages/agent-core-v2/src/_base/di/fiber.ts

@@ -0,0 +1,714 @@
+import type { IDisposable } from './lifecycle';
+import type { Emitter } from '../event';
+import { isPromiseLike, type EffectBody } from '../lifecycle/disposer';
+import { Ledger, type LedgerEntry } from '../lifecycle/ledger';
+import {
+  collection,
+  isCollectionToken,
+  type CollectionToken,
+  type CollectionView,
+} from './collection';
+import { SyncDescriptor } from './descriptors';
+import {
+  isServiceIdentifier,
+  ScopeActivation,
+  _util,
+  type LiveRef,
+  type ServiceIdentifier,
+} from './instantiation';
+
+export enum FiberState {
+  Pending = 0,
+  Activating = 1,
+  Active = 2,
+  Unloading = 3,
+  Failed = 4,
+}
+
+export interface ConfigSchema {
+  readonly '~standard': {
+    readonly validate: (value: unknown) => unknown;
+  };
+}
+
+export interface RecipeStatics {
+  readonly name?: string;
+  readonly inject?: readonly ServiceIdentifier<any>[];
+  readonly Config?: ConfigSchema;
+  readonly meta?: Record<string, unknown>;
+}
+
+export type ServiceClassRecipe =
+  (new (...args: any[]) => unknown) & RecipeStatics;
+
+export type ServiceFunctionRecipe = ((
+  fiber: Fiber,
+  config?: any,
+) => any) &
+  RecipeStatics;
+
+export type ServiceObjectRecipe = {
+  apply(
+    fiber: Fiber,
+    config?: any,
+  ): any;
+} & RecipeStatics;
+
+export type ServiceRecipe =
+  | ServiceClassRecipe
+  | ServiceFunctionRecipe
+  | ServiceObjectRecipe;
+
+export interface FiberProvideOptions {
+  readonly config?: unknown;
+  readonly activation?: ScopeActivation;
+}
+
+export interface Fiber {
+  readonly name: string;
+  readonly state: FiberState;
+  readonly config: unknown;
+
+  provide<T>(
+    id: ServiceIdentifier<T>,
+    recipe: ServiceClassRecipe,
+    opts?: FiberProvideOptions,
+  ): FiberHandle<T>;
+  provide<T>(id: ServiceIdentifier<T>, instance: T): FiberHandle<T>;
+  provide(recipe: ServiceRecipe, opts?: FiberProvideOptions): FiberHandle;
+  provide<T>(token: CollectionToken<T>, value: T): FiberHandle;
+
+  effect(body: EffectBody, label?: string): FiberHandle;
+
+  on(event: string | Emitter<any>, handler: (e: any) => void): FiberHandle;
+
+  get<T>(id: ServiceIdentifier<T>): T;
+  ref<T>(id: ServiceIdentifier<T>): LiveRef<T>;
+}
+
+export interface FiberHandle<T = unknown> extends PromiseLike<FiberHandle<T>> {
+  readonly name: string;
+  readonly state: FiberState;
+  readonly uid: number;
+  update(config?: unknown): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+export class FiberProtocolError extends Error {
+  constructor(detail: string) {
+    super(detail);
+    this.name = 'FiberProtocolError';
+  }
+}
+
+export class ServiceRecipeError extends Error {
+  constructor(detail: string) {
+    super(detail);
+    this.name = 'ServiceRecipeError';
+  }
+}
+
+export interface ConstructionFrame {
+  readonly ctor: new (...args: any[]) => any;
+  readonly config: unknown;
+  readonly token: ServiceIdentifier<any> | undefined;
+  readonly host: FiberHost;
+}
+
+const _constructionStack: ConstructionFrame[] = [];
+
+export function pushConstructionFrame(frame: ConstructionFrame): void {
+  _constructionStack.push(frame);
+}
+
+export function popConstructionFrame(): void {
+  _constructionStack.pop();
+}
+
+export function currentConstruction(): ConstructionFrame | undefined {
+  return _constructionStack.at(-1);
+}
+
+export const SERVICE_MARK = Symbol('serviceUnit');
+
+export function isServiceRecipe(ctor: any): ctor is ServiceClassRecipe {
+  return typeof ctor === 'function' && ctor.prototype?.[SERVICE_MARK] === true;
+}
+
+export function isClassRecipe(recipe: unknown): recipe is ServiceClassRecipe {
+  return (
+    typeof recipe === 'function' &&
+    Object.prototype.hasOwnProperty.call(recipe, 'prototype')
+  );
+}
+
+export type BufferedOp = (runtime: Fiber) => void;
+
+export interface UnitInternals {
+  readonly unitBook: Ledger;
+  takeUnitBuffer(): BufferedOp[] | null;
+  setUnitRuntime(runtime: Fiber): void;
+}
+
+export interface FiberHost {
+  mintUid(): number;
+  provideToken<T>(
+    id: ServiceIdentifier<T>,
+    descriptor: SyncDescriptor<T>,
+    options: {
+      readonly activation: 'eager' | 'ondemand';
+      readonly config?: unknown;
+    },
+  ): TokenProvideCore;
+  provideTokenInstance<T>(id: ServiceIdentifier<T>, instance: T): TokenProvideCore;
+  tokenState(id: ServiceIdentifier<any>): string | undefined;
+  updateToken(id: ServiceIdentifier<any>, config: unknown, hasConfig: boolean): Promise<void>;
+  resolveTokenWhenAvailable<T>(id: ServiceIdentifier<T>): Promise<T>;
+  resolveInstance<T>(id: ServiceIdentifier<T>): T;
+  materializedInstance<T>(id: ServiceIdentifier<T>): T | undefined;
+  liveRef<T>(id: ServiceIdentifier<T>): LiveRef<T>;
+  recordInstanceEdge(node: object | undefined, id: ServiceIdentifier<any>): void;
+  collectionView<T>(token: CollectionToken<T>): CollectionView<T>;
+  addCollectionRecord<T>(
+    token: CollectionToken<T>,
+    providerName: string,
+    providerBook: Ledger,
+    value: T,
+  ): () => void;
+  constructService<T>(ctor: new (...args: any[]) => T, config: unknown): T;
+}
+
+export interface TokenProvideCore {
+  uid(): number;
+  dispose(): Promise<void>;
+  release(): void;
+}
+
+export type FiberEventResolver = (
+  host: FiberHost,
+  event: string,
+  handler: (e: any) => void,
+) => IDisposable;
+
+let _eventResolver: FiberEventResolver | undefined;
+
+export function setFiberEventResolver(resolver: FiberEventResolver | undefined): void {
+  _eventResolver = resolver;
+}
+
+export function bindServiceUnit(instance: UnitInternals & IDisposable, frame: ConstructionFrame): void {
+  const buffer = instance.takeUnitBuffer();
+  if (buffer === null) {
+    return;
+  }
+  const ctor = (instance as any).constructor as ServiceClassRecipe;
+  const runtime = new FiberRuntime(
+    frame.host,
+    instance.unitBook,
+    recipeName(ctor),
+    frame.config,
+    frame.token,
+    new Set(_util.getInstanceDependencies(ctor as unknown as _util.DI_TARGET_OBJ).map((d) => d.id)),
+    instance,
+  );
+  instance.setUnitRuntime(runtime);
+  try {
+    for (const op of buffer) {
+      op(runtime);
+    }
+  } catch (error) {
+    instance.dispose();
+    throw error;
+  }
+}
+
+function recipeName(recipe: RecipeStatics & { name?: string }): string {
+  return recipe.name ?? 'anonymous';
+}
+
+function validateConfig(schema: ConfigSchema | undefined, config: unknown, name: string): unknown {
+  if (schema === undefined) {
+    return config;
+  }
+  const out = schema['~standard'].validate(config);
+  if (isPromiseLike(out)) {
+    throw new ServiceRecipeError(`config schema of unit '${name}' must validate synchronously`);
+  }
+  const result = out as {
+    readonly value?: unknown;
+    readonly issues?: ReadonlyArray<{ readonly message: string }>;
+  };
+  if (result.issues !== undefined && result.issues.length > 0) {
+    throw new ServiceRecipeError(
+      `invalid config for unit '${name}': ${result.issues.map((issue) => issue.message).join('; ')}`,
+    );
+  }
+  return 'value' in result ? result.value : config;
+}
+
+function mapUnitState(state: string | undefined): FiberState {
+  if (state === undefined) {
+    return FiberState.Active;
+  }
+  switch (state) {
+    case 'Pending':
+      return FiberState.Pending;
+    case 'Activating':
+      return FiberState.Activating;
+    case 'Unloading':
+      return FiberState.Unloading;
+    case 'Failed':
+      return FiberState.Failed;
+    default:
+      return FiberState.Active;
+  }
+}
+
+export class FiberRuntime implements Fiber {
+  constructor(
+    private readonly _host: FiberHost,
+    private readonly _book: Ledger,
+    readonly name: string,
+    readonly config: unknown,
+    private readonly _token: ServiceIdentifier<any> | undefined,
+    private readonly _declared: ReadonlySet<ServiceIdentifier<any>>,
+    private readonly _edgeNode: object | undefined,
+  ) {}
+
+  get state(): FiberState {
+    if (this._token !== undefined) {
+      return mapUnitState(this._host.tokenState(this._token));
+    }
+    return FiberState.Active;
+  }
+
+  provide<T>(
+    id: ServiceIdentifier<T>,
+    recipe: ServiceClassRecipe,
+    opts?: FiberProvideOptions,
+  ): FiberHandle<T>;
+  provide<T>(id: ServiceIdentifier<T>, instance: T): FiberHandle<T>;
+  provide(recipe: ServiceRecipe, opts?: FiberProvideOptions): FiberHandle;
+  provide<T>(token: CollectionToken<T>, value: T): FiberHandle;
+  provide(
+    first: ServiceIdentifier<any> | ServiceRecipe | CollectionToken<any>,
+    second?: any,
+    third?: FiberProvideOptions,
+  ): FiberHandle {
+    if (isCollectionToken(first)) {
+      return this._provideRecord(first, second);
+    }
+    if (isServiceIdentifier(first)) {
+      if (isClassRecipe(second)) {
+        return this._provideToken(first, second, third);
+      }
+      if (
+        typeof second === 'function' ||
+        (second !== null && typeof second === 'object' && typeof second.apply === 'function')
+      ) {
+        throw new ServiceRecipeError(
+          `token-bound provide of '${String(first)}' requires a class recipe or an instance (function/object recipes are only valid for the anonymous form)`,
+        );
+      }
+      return this._provideTokenInstance(first, second);
+    }
+    return this._provideAnonymous(first as ServiceRecipe, second as FiberProvideOptions | undefined);
+  }
+
+  effect(body: EffectBody, label?: string): FiberHandle {
+    const entry = this._book.effect(body, label ?? `effect:${this.name}`);
+    return new BasicFiberHandle({
+      name: label ?? `effect:${this.name}`,
+      uid: this._host.mintUid(),
+      state: () => (entry.disposed ? FiberState.Unloading : FiberState.Active),
+      update: async () => {
+        await entry.dispose();
+        if (this._book.isActive) {
+          this._book.effect(body, label ?? `effect:${this.name}`);
+        }
+      },
+      dispose: async () => {
+        await entry.dispose();
+      },
+      whenActive: () => Promise.resolve(),
+    });
+  }
+
+  on(event: string | Emitter<any>, handler: (e: any) => void): FiberHandle {
+    let subscription: IDisposable;
+    if (typeof event === 'string') {
+      if (_eventResolver === undefined) {
+        throw new FiberProtocolError(
+          `no event resolver registered — cannot subscribe to '${event}'`,
+        );
+      }
+      subscription = _eventResolver(this._host, event, handler);
+    } else if (typeof event?.event === 'function') {
+      subscription = event.event(handler);
+    } else {
+      throw new FiberProtocolError(`unsupported event source for unit '${this.name}'`);
+    }
+    const label = typeof event === 'string' ? `on:${event}` : `on:${event.constructor?.name ?? 'emitter'}`;
+    const entry = this._book.register(() => {
+      subscription.dispose();
+    }, label);
+    return new BasicFiberHandle({
+      name: label,
+      uid: this._host.mintUid(),
+      state: () => (entry.disposed ? FiberState.Unloading : FiberState.Active),
+      update: async () => {},
+      dispose: async () => {
+        await entry.dispose();
+      },
+      whenActive: () => Promise.resolve(),
+    });
+  }
+
+  get<T>(id: ServiceIdentifier<T>): T {
+    if (!this._declared.has(id)) {
+      throw new FiberProtocolError(
+        `unit '${this.name}' resolves undeclared dependency '${String(id)}' — declare it as a constructor parameter (class recipe) or in the inject static (function recipe)`,
+      );
+    }
+    this._host.recordInstanceEdge(this._edgeNode, id);
+    return this._host.resolveInstance(id);
+  }
+
+  ref<T>(id: ServiceIdentifier<T>): LiveRef<T> {
+    return this._host.liveRef(id);
+  }
+
+  private _provideToken<T>(
+    id: ServiceIdentifier<T>,
+    recipe: ServiceClassRecipe,
+    opts: FiberProvideOptions | undefined,
+  ): FiberHandle<T> {
+    if (!isClassRecipe(recipe)) {
+      throw new ServiceRecipeError(
+        `token-bound provide of '${String(id)}' requires a class recipe (function/object recipes are only valid for the anonymous form)`,
+      );
+    }
+    const name = recipe.name ?? String(id);
+    const config = validateConfig(recipe.Config, opts?.config, name);
+    const core = this._host.provideToken(
+      id,
+      new SyncDescriptor<T>(recipe as new (...args: any[]) => T),
+      {
+        activation: opts?.activation === ScopeActivation.OnDemand ? 'ondemand' : 'eager',
+        config,
+      },
+    );
+    const entry = this._book.register(() => core.dispose(), `provide:${String(id)}`);
+    return new BasicFiberHandle<T>({
+      name,
+      uid: undefined,
+      uidOf: () => core.uid(),
+      state: () => mapUnitState(this._host.tokenState(id)),
+      update: (next) => {
+        const hasConfig = next !== undefined;
+        return this._host.updateToken(
+          id,
+          hasConfig ? validateConfig(recipe.Config, next, name) : undefined,
+          hasConfig,
+        );
+      },
+      dispose: async () => {
+        await entry.dispose();
+      },
+      whenActive: () => this._host.resolveTokenWhenAvailable(id).then(() => undefined),
+    });
+  }
+
+  private _provideTokenInstance<T>(id: ServiceIdentifier<T>, instance: T): FiberHandle<T> {
+    const core = this._host.provideTokenInstance(id, instance);
+    const entry = this._book.register(() => core.dispose(), `provide:${String(id)}`);
+    return new BasicFiberHandle<T>({
+      name: String(id),
+      uid: undefined,
+      uidOf: () => core.uid(),
+      state: () => mapUnitState(this._host.tokenState(id)),
+      update: () => this._host.updateToken(id, undefined, false),
+      dispose: async () => {
+        await entry.dispose();
+      },
+      whenActive: () => this._host.resolveTokenWhenAvailable(id).then(() => undefined),
+    });
+  }
+
+  private _provideAnonymous(recipe: ServiceRecipe, opts: FiberProvideOptions | undefined): FiberHandle {
+    if (isClassRecipe(recipe)) {
+      return this._provideAnonymousClass(recipe, opts);
+    }
+    return this._provideFunction(recipe, opts);
+  }
+
+  private _provideAnonymousClass(recipe: ServiceClassRecipe, opts: FiberProvideOptions | undefined): FiberHandle {
+    const name = recipeName(recipe);
+    let config = validateConfig(recipe.Config, opts?.config, name);
+    let state = FiberState.Activating;
+    let failure: unknown;
+    let instance: unknown;
+    let entry: LedgerEntry | undefined;
+    const construct = (nextConfig: unknown): void => {
+      state = FiberState.Activating;
+      instance = this._host.constructService(recipe, nextConfig);
+      entry = this._book.register(() => {
+        state = FiberState.Unloading;
+        (instance as Partial<IDisposable>).dispose?.();
+      }, `provide:${name}`);
+      state = FiberState.Active;
+    };
+    try {
+      construct(config);
+    } catch (error) {
+      state = FiberState.Failed;
+      failure = error;
+      throw error;
+    }
+    for (const dependency of _util.getInstanceDependencies(recipe as unknown as _util.DI_TARGET_OBJ)) {
+      this._host.recordInstanceEdge(this._edgeNode, dependency.id);
+    }
+    return new BasicFiberHandle({
+      name,
+      uid: this._host.mintUid(),
+      state: () => state,
+      update: async (next) => {
+        await entry?.dispose();
+        entry = undefined;
+        try {
+          if (next !== undefined) {
+            config = validateConfig(recipe.Config, next, name);
+          }
+          construct(config);
+        } catch (error) {
+          state = FiberState.Failed;
+          failure = error;
+          throw error;
+        }
+      },
+      dispose: async () => {
+        await entry?.dispose();
+        entry = undefined;
+      },
+      whenActive: () => (failure !== undefined ? Promise.reject(failure) : Promise.resolve()),
+    });
+  }
+
+  private _provideFunction(recipe: ServiceFunctionRecipe | ServiceObjectRecipe, opts: FiberProvideOptions | undefined): FiberHandle {
+    const name = recipeName(recipe);
+    const config = validateConfig(recipe.Config, opts?.config, name);
+    const book = new Ledger(`unit:${name}`);
+    const anchor = this._book.register((reason) => book.teardown(reason), `provide:${name}`);
+    const facade = new FiberRuntime(
+      this._host,
+      book,
+      name,
+      config,
+      undefined,
+      new Set(recipe.inject ?? []),
+      this._edgeNode,
+    );
+    const run = (): void => {
+      let out: unknown;
+      if (typeof recipe === 'function') {
+        out = recipe(facade, config);
+      } else {
+        out = recipe.apply(facade, config);
+      }
+      book.effect((() => out) as EffectBody, `effect:${name}`);
+    };
+    try {
+      run();
+    } catch (error) {
+      void book.teardown('unload');
+      anchor.release();
+      throw error;
+    }
+    return new BasicFiberHandle({
+      name,
+      uid: this._host.mintUid(),
+      state: () => (anchor.disposed ? FiberState.Unloading : FiberState.Active),
+      update: async () => {
+        await book.clear('unload');
+        try {
+          run();
+        } catch (error) {
+          void book.teardown('unload');
+          anchor.release();
+          throw error;
+        }
+      },
+      dispose: async () => {
+        await anchor.dispose();
+      },
+      whenActive: () => Promise.resolve(),
+    });
+  }
+
+  private _provideRecord<T>(token: CollectionToken<T>, value: T): FiberHandle {
+    const remove = this._host.addCollectionRecord(token, this.name, this._book, value);
+    const entry = this._book.register(() => {
+      remove();
+    }, `provide:${token.name}`);
+    return new BasicFiberHandle({
+      name: `${this.name}→${token.name}`,
+      uid: this._host.mintUid(),
+      state: () => (entry.disposed ? FiberState.Unloading : FiberState.Active),
+      update: async () => {},
+      dispose: async () => {
+        await entry.dispose();
+      },
+      whenActive: () => Promise.resolve(),
+    });
+  }
+}
+
+interface BasicHandleParts {
+  readonly name: string;
+  readonly uid?: number;
+  readonly uidOf?: () => number;
+  readonly state: () => FiberState;
+  readonly update: (config: unknown) => Promise<void>;
+  readonly dispose: () => Promise<void>;
+  readonly whenActive: () => Promise<void>;
+}
+
+class BasicFiberHandle<T> implements FiberHandle<T> {
+  constructor(private readonly _parts: BasicHandleParts) {}
+
+  get name(): string {
+    return this._parts.name;
+  }
+
+  get state(): FiberState {
+    return this._parts.state();
+  }
+
+  get uid(): number {
+    if (this._parts.uidOf !== undefined) {
+      return this._parts.uidOf();
+    }
+    return this._parts.uid!;
+  }
+
+  update(config?: unknown): Promise<void> {
+    return this._parts.update(config);
+  }
+
+  dispose(): Promise<void> {
+    return this._parts.dispose();
+  }
+
+  // eslint-disable-next-line eslint-plugin-unicorn(no-thenable)
+  then<TResult1 = FiberHandle<T>, TResult2 = never>(
+    onfulfilled?: ((value: FiberHandle<T>) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): PromiseLike<TResult1 | TResult2> {
+    return thenSettle(this._parts.whenActive().then(() => settledView(this)), onfulfilled, onrejected);
+  }
+}
+
+interface SettledHandleView {
+  readonly name: string;
+  readonly state: FiberState;
+  readonly uid: number;
+  update(config?: unknown): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+function settledView<T>(handle: FiberHandle<T>): SettledHandleView {
+  return {
+    get name() {
+      return handle.name;
+    },
+    get state() {
+      return handle.state;
+    },
+    get uid() {
+      return handle.uid;
+    },
+    update: (config?: unknown) => handle.update(config),
+    dispose: () => handle.dispose(),
+  };
+}
+
+function thenSettle<T, TResult1, TResult2>(
+  settled: Promise<SettledHandleView>,
+  onfulfilled: ((value: FiberHandle<T>) => TResult1 | PromiseLike<TResult1>) | null | undefined,
+  onrejected: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined,
+): PromiseLike<TResult1 | TResult2> {
+  return settled.then(
+    onfulfilled as unknown as (value: SettledHandleView) => TResult1 | PromiseLike<TResult1>,
+    onrejected,
+  );
+}
+
+export class PendingFiberHandle<T> implements FiberHandle<T> {
+  private _real: FiberHandle<T> | undefined;
+  private _disposed = false;
+
+  constructor(private readonly _pendingName: string) {}
+
+  attach(real: FiberHandle<T>): void {
+    if (this._disposed) {
+      void real.dispose();
+      return;
+    }
+    this._real = real;
+  }
+
+  get name(): string {
+    return this._real?.name ?? this._pendingName;
+  }
+
+  get state(): FiberState {
+    return this._real?.state ?? FiberState.Activating;
+  }
+
+  get uid(): number {
+    if (this._real === undefined) {
+      throw new FiberProtocolError(
+        `handle '${this._pendingName}' has not been flushed yet (construction protocol)`,
+      );
+    }
+    return this._real.uid;
+  }
+
+  update(config?: unknown): Promise<void> {
+    if (this._real === undefined) {
+      return Promise.reject(
+        new FiberProtocolError(`handle '${this._pendingName}' has not been flushed yet`),
+      );
+    }
+    return this._real.update(config);
+  }
+
+  async dispose(): Promise<void> {
+    this._disposed = true;
+    await this._real?.dispose();
+  }
+
+  // eslint-disable-next-line eslint-plugin-unicorn(no-thenable) — FiberHandle is a thenable by design
+  then<TResult1 = FiberHandle<T>, TResult2 = never>(
+    onfulfilled?: ((value: FiberHandle<T>) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): PromiseLike<TResult1 | TResult2> {
+    if (this._real !== undefined) {
+      return this._real.then(onfulfilled, onrejected);
+    }
+    return thenSettle(Promise.resolve(settledView(this)), onfulfilled, onrejected);
+  }
+}
+
+const _scopeUnitsTokens = new Map<string, CollectionToken<ServiceRecipe>>();
+
+export function ScopeUnits(kind: string): CollectionToken<ServiceRecipe> {
+  let token = _scopeUnitsTokens.get(kind);
+  if (token === undefined) {
+    token = collection<ServiceRecipe>(`scope-units:${kind}`);
+    _scopeUnitsTokens.set(kind, token);
+  }
+  return token;
+}
+
+export type { EffectBody };

packages/agent-core-v2/src/_base/di/graph.ts

@@ -0,0 +1,89 @@
+export class Node<T> {
+  readonly incoming = new Map<string, Node<T>>();
+  readonly outgoing = new Map<string, Node<T>>();
+
+  constructor(
+    readonly key: string,
+    readonly data: T
+  ) { }
+}
+
+export class Graph<T> {
+  private readonly _nodes = new Map<string, Node<T>>();
+
+  constructor(private readonly _hashFn: (element: T) => string) { }
+
+  roots(): Node<T>[] {
+    const ret: Node<T>[] = [];
+    for (const node of this._nodes.values()) {
+      if (node.outgoing.size === 0) {
+        ret.push(node);
+      }
+    }
+    return ret;
+  }
+
+  insertEdge(from: T, to: T): void {
+    const fromNode = this.lookupOrInsertNode(from);
+    const toNode = this.lookupOrInsertNode(to);
+    fromNode.outgoing.set(toNode.key, toNode);
+    toNode.incoming.set(fromNode.key, fromNode);
+  }
+
+  removeNode(data: T): void {
+    const key = this._hashFn(data);
+    this._nodes.delete(key);
+    for (const node of this._nodes.values()) {
+      node.outgoing.delete(key);
+      node.incoming.delete(key);
+    }
+  }
+
+  lookupOrInsertNode(data: T): Node<T> {
+    const key = this._hashFn(data);
+    let node = this._nodes.get(key);
+    if (!node) {
+      node = new Node(key, data);
+      this._nodes.set(key, node);
+    }
+    return node;
+  }
+
+  isEmpty(): boolean {
+    return this._nodes.size === 0;
+  }
+
+  toString(): string {
+    const data: string[] = [];
+    for (const [key, value] of this._nodes) {
+      data.push(`${key}\n\t(-> incoming)[${[...value.incoming.keys()].join(', ')}]\n\t(outgoing ->)[${[...value.outgoing.keys()].join(',')}]\n`);
+    }
+    return data.join('\n');
+  }
+
+  findCycleSlow() {
+    for (const [id, node] of this._nodes) {
+      const seen = new Set<string>([id]);
+      const res = this._findCycle(node, seen);
+      if (res) {
+        return res;
+      }
+    }
+    return undefined;
+  }
+
+  private _findCycle(node: Node<T>, seen: Set<string>): string | undefined {
+    for (const [id, outgoing] of node.outgoing) {
+      if (seen.has(id)) {
+        return [...seen, id].join(' -> ');
+      }
+      seen.add(id);
+      const value = this._findCycle(outgoing, seen);
+      if (value) {
+        return value;
+      }
+      seen.delete(id);
+    }
+    return undefined;
+  }
+}

packages/agent-core-v2/src/_base/di/instantiation.ts

@@ -0,0 +1,212 @@
+import type { SyncDescriptor, SyncDescriptor0 } from './descriptors';
+import type { CascadeEngine } from './cascadeEngine';
+import type { Event } from '../event';
+import type { DisposableStore, IDisposable } from './lifecycle';
+import type { ServiceCollection } from './serviceCollection';
+
+export type DependencyKind = 'instance' | 'collection' | 'ref';
+
+export namespace _util {
+  export const serviceIds = new Map<string, ServiceIdentifier<any>>();
+  export const DI_TARGET = '$di$target';
+  export const DI_DEPENDENCIES = '$di$dependencies';
+
+  export interface ServiceDependency {
+    readonly id: ServiceIdentifier<any>;
+    readonly index: number;
+    readonly kind: DependencyKind;
+  }
+
+  export function getServiceDependencies(
+    ctor: DI_TARGET_OBJ,
+  ): ServiceDependency[] {
+    return ctor[DI_DEPENDENCIES] || [];
+  }
+
+  export function getInstanceDependencies(
+    ctor: DI_TARGET_OBJ,
+  ): ServiceDependency[] {
+    return getServiceDependencies(ctor).filter(
+      (dependency) => dependency.kind === 'instance',
+    );
+  }
+
+  export interface DI_TARGET_OBJ extends Function {
+    [DI_TARGET]: Function;
+    [DI_DEPENDENCIES]: { id: ServiceIdentifier<any>; index: number; kind: DependencyKind }[];
+  }
+}
+
+export type BrandedService = { _serviceBrand: undefined };
+
+export interface IConstructorSignature<T, Args extends any[] = []> {
+  new <Services extends BrandedService[]>(...args: [...Args, ...Services]): T;
+}
+
+export type GetLeadingNonServiceArgs<TArgs extends any[]> =
+  TArgs extends [] ? []
+  : TArgs extends [...infer TFirst, BrandedService] ? GetLeadingNonServiceArgs<TFirst>
+  : TArgs;
+
+export interface ServiceIdentifier<T> {
+  (target: any, key: string | symbol | undefined, index: number): void;
+
+  readonly type: T;
+
+  toString(): string;
+}
+
+function storeServiceDependency(
+  id: ServiceIdentifier<any>,
+  target: Function,
+  index: number,
+  kind: DependencyKind = 'instance',
+): void {
+  const t = target as _util.DI_TARGET_OBJ;
+  if (t[_util.DI_TARGET] === target) {
+    t[_util.DI_DEPENDENCIES].push({ id, index, kind });
+  } else {
+    t[_util.DI_DEPENDENCIES] = [{ id, index, kind }];
+    t[_util.DI_TARGET] = target;
+  }
+}
+
+export function storeCustomDependency(
+  id: ServiceIdentifier<any>,
+  kind: DependencyKind,
+  target: any,
+  index: number,
+): void {
+  storeServiceDependency(id, target, index, kind);
+}
+
+export function createDecorator<T>(name: string): ServiceIdentifier<T> {
+  const existing = _util.serviceIds.get(name);
+  if (existing) {
+    return existing as ServiceIdentifier<T>;
+  }
+
+  const id = function serviceDecorator(
+    target: any,
+    _key: string | symbol | undefined,
+    index: number,
+  ): void {
+    if (arguments.length !== 3) {
+      throw new Error(
+        '@IServiceName-decorator can only be used to decorate a parameter',
+      );
+    }
+    storeServiceDependency(id, target, index);
+  } as unknown as ServiceIdentifier<T>;
+
+  Object.defineProperty(id, 'toString', {
+    value: function toString(): string {
+      return name;
+    },
+    enumerable: false,
+    writable: false,
+    configurable: false,
+  });
+  Object.defineProperty(id, SERVICE_IDENTIFIER_MARK, { value: true, enumerable: false });
+
+  _util.serviceIds.set(name, id);
+  return id;
+}
+
+const SERVICE_IDENTIFIER_MARK = Symbol('serviceIdentifier');
+
+export function isServiceIdentifier(thing: unknown): thing is ServiceIdentifier<unknown> {
+  return (
+    typeof thing === 'function' &&
+    (thing as unknown as Record<symbol, unknown>)[SERVICE_IDENTIFIER_MARK] === true
+  );
+}
+
+export function refineServiceDecorator<T1, T extends T1>(
+  serviceIdentifier: ServiceIdentifier<T1>,
+): ServiceIdentifier<T> {
+  return serviceIdentifier as ServiceIdentifier<T>;
+}
+
+export enum ScopeActivation {
+  OnScopeCreated = 0,
+  OnDemand = 1,
+}
+
+export interface LiveRef<T> {
+  readonly current: T | undefined;
+  readonly onDidChange: Event<void>;
+}
+
+export function ref<T>(
+  id: ServiceIdentifier<T>,
+): (target: object, key: string | symbol | undefined, index: number) => void {
+  return function refDecorator(target: any, _key: string | symbol | undefined, index: number): void {
+    if (arguments.length !== 3) {
+      throw new Error('@ref-decorator can only be used to decorate a parameter');
+    }
+    storeServiceDependency(id, target, index, 'ref');
+  };
+}
+
+export interface ServicesAccessor {
+  get<T>(id: ServiceIdentifier<T>): T;
+}
+
+export interface ProvideOptions {
+  readonly activation?: 'eager' | 'ondemand';
+  readonly config?: unknown;
+}
+
+export interface ProvideAllEntry<T = unknown> {
+  readonly id: ServiceIdentifier<T>;
+  readonly descriptor: SyncDescriptor<T>;
+  readonly options?: ProvideOptions;
+}
+
+export interface ProvideHandle extends IDisposable {
+  readonly uid: number;
+}
+
+export interface IInstantiationService {
+  readonly _serviceBrand: undefined;
+
+  readonly cascade: CascadeEngine;
+
+  invokeFunction<R, TS extends any[] = []>(
+    fn: (accessor: ServicesAccessor, ...args: TS) => R,
+    ...args: TS
+  ): R;
+  createInstance<T>(descriptor: SyncDescriptor0<T>): T;
+  createInstance<
+    Ctor extends new (
+      ...args: any[]
+    ) => unknown,
+    R extends InstanceType<Ctor>,
+  >(
+    ctor: Ctor,
+    ...args: GetLeadingNonServiceArgs<ConstructorParameters<Ctor>>
+  ): R;
+  createChild(services: ServiceCollection, store?: DisposableStore): IInstantiationService;
+  provide<T>(
+    id: ServiceIdentifier<T>,
+    instanceOrDescriptor: T | SyncDescriptor<T>,
+    options?: ProvideOptions,
+  ): ProvideHandle;
+  provideAll(entries: ReadonlyArray<ProvideAllEntry>): void;
+  unprovide<T>(id: ServiceIdentifier<T>): void;
+  dispose(): void;
+  disposeAsync(): Promise<void>;
+}
+
+export const IInstantiationService: ServiceIdentifier<IInstantiationService> =
+  createDecorator<IInstantiationService>('instantiationService');
+
+export interface ServiceCollectionLike {
+  set<T>(id: ServiceIdentifier<T>, instanceOrDescriptor: any): unknown;
+  get<T>(id: ServiceIdentifier<T>): any;
+  has(id: ServiceIdentifier<any>): boolean;
+  forEach(
+    callback: (id: ServiceIdentifier<any>, value: any) => void,
+  ): void;
+}

packages/agent-core-v2/src/_base/di/instantiationService.ts

@@ -0,0 +1,1006 @@
+import { SyncDescriptor } from './descriptors';
+import { CascadeEngine, CascadeTree, type CascadeChange, type CascadeHost } from './cascadeEngine';
+import {
+  CollectionStore,
+  type CollectionToken,
+  type CollectionView,
+  type CollectionViewImpl,
+} from './collection';
+import { DependencyGraph } from './dependencyGraph';
+import { CascadeConflictError, CyclicDependencyError } from './errors';
+import {
+  bindServiceUnit,
+  isServiceRecipe,
+  pushConstructionFrame,
+  popConstructionFrame,
+  type ConstructionFrame,
+  type FiberHost,
+  type TokenProvideCore,
+  type UnitInternals,
+} from './fiber';
+import { Graph } from './graph';
+import {
+  IInstantiationService as IInstantiationServiceDecorator,
+  _util,
+  type IInstantiationService,
+  type LiveRef,
+  type ProvideAllEntry,
+  type ProvideHandle,
+  type ProvideOptions,
+  type ServiceIdentifier,
+  type ServicesAccessor,
+} from './instantiation';
+import { isDisposable, type DisposableStore, type IDisposable } from './lifecycle';
+import { onUnexpectedError } from '../errors/unexpectedError';
+import { Emitter } from '../event';
+import { Ledger, type LedgerEntry } from '../lifecycle/ledger';
+import type { Disposer } from '../lifecycle/disposer';
+import { ServiceCollection } from './serviceCollection';
+
+const enum TraceType {
+  None = 0,
+  Creation = 1,
+  Invocation = 2,
+  Branch = 3,
+}
+
+export class Trace {
+  static readonly all = new Set<string>();
+
+  private static readonly _None = new class extends Trace {
+    constructor() { super(TraceType.None, null); }
+    override stop() { }
+    override branch() { return this; }
+  };
+
+  static traceInvocation(_enableTracing: boolean, fn: any): Trace {
+    return !_enableTracing
+      ? Trace._None
+      : new Trace(
+          TraceType.Invocation,
+          fn.name ?? new Error('Trace invocation').stack!.split('\n').slice(3, 4).join('\n'),
+        );
+  }
+
+  static traceCreation(_enableTracing: boolean, ctor: any): Trace {
+    return !_enableTracing ? Trace._None : new Trace(TraceType.Creation, ctor.name);
+  }
+
+  private static _totals: number = 0;
+  private readonly _start: number = Date.now();
+  private readonly _dep: [ServiceIdentifier<any>, boolean, Trace?][] = [];
+
+  private constructor(
+    readonly type: TraceType,
+    readonly name: string | null
+  ) { }
+
+  branch(id: ServiceIdentifier<any>, first: boolean): Trace {
+    const child = new Trace(TraceType.Branch, id.toString());
+    this._dep.push([id, first, child]);
+    return child;
+  }
+
+  stop() {
+    const dur = Date.now() - this._start;
+    Trace._totals += dur;
+
+    let causedCreation = false;
+
+    function printChild(n: number, trace: Trace) {
+      const res: string[] = [];
+      const prefix = '\t'.repeat(n);
+      for (const [id, first, child] of trace._dep) {
+        if (first && child) {
+          causedCreation = true;
+          res.push(`${prefix}CREATES -> ${String(id)}`);
+          const nested = printChild(n + 1, child);
+          if (nested) {
+            res.push(nested);
+          }
+        } else {
+          res.push(`${prefix}uses -> ${String(id)}`);
+        }
+      }
+      return res.join('\n');
+    }
+
+    const lines = [
+      `${this.type === TraceType.Creation ? 'CREATE' : 'CALL'} ${this.name}`,
+      printChild(1, this),
+      `DONE, took ${dur.toFixed(2)}ms (grand total ${Trace._totals.toFixed(2)}ms)`,
+    ];
+
+    if (dur > 2 || causedCreation) {
+      Trace.all.add(lines.join('\n'));
+    }
+  }
+
+}
+
+export class InstantiationService implements IInstantiationService {
+  declare readonly _serviceBrand: undefined;
+
+  readonly _globalGraph?: Graph<string>;
+
+  protected readonly _parent?: InstantiationService;
+
+  protected readonly _ledger = new Ledger('InstantiationService');
+
+  get dependencyGraph(): DependencyGraph {
+    return this._tree.graph;
+  }
+
+  private readonly _tree: CascadeTree;
+
+  readonly cascade: CascadeEngine;
+
+  private _parentLedgerEntry: LedgerEntry | undefined;
+
+  private readonly _instanceEntries = new Map<unknown, LedgerEntry>();
+
+  private readonly _provideEntries = new Map<
+    ServiceIdentifier<any>,
+    { readonly entry: LedgerEntry; readonly core: TokenProvideCore }
+  >();
+
+  private _cascadeResolving = false;
+
+  protected readonly _children = new Set<InstantiationService>();
+
+  private readonly _inProgress: ServiceIdentifier<any>[] = [];
+
+  private readonly _activeInstantiations = new Set<ServiceIdentifier<any>>();
+
+  private readonly _collectionStore: CollectionStore;
+
+  private readonly _collectionViews = new Map<
+    CollectionToken<unknown>,
+    CollectionViewImpl<any>
+  >();
+
+  private readonly _edgeNodes = new Set<object>();
+
+  debugLabel: string | undefined;
+
+  private _fiberHost: FiberHost | undefined;
+
+  private _disposed = false;
+
+  constructor(
+    private readonly _services: ServiceCollection = new ServiceCollection(),
+    private readonly _strict: boolean = false,
+    parent?: InstantiationService,
+    protected readonly _enableTracing: boolean = false,
+  ) {
+    this._parent = parent;
+    this._globalGraph = _enableTracing ? parent?._globalGraph ?? new Graph(e => e) : undefined;
+    this._services.set(IInstantiationServiceDecorator, this);
+    this._tree = parent?._tree ?? new CascadeTree(new DependencyGraph());
+    this._collectionStore =
+      parent?._collectionStore ??
+      new CollectionStore((container) => (container as InstantiationService)._parent);
+    const host: CascadeHost = {
+      isRegistered: (token) => this._getServiceInstanceOrDescriptor(token) !== undefined,
+      ownerScopeOf: (token) => this._ownerOf(token),
+      isMaterialized: (token) => {
+        const value = this._services.get(token);
+        return value !== undefined && !(value instanceof SyncDescriptor);
+      },
+      materialize: (token) => {
+        this._cascadeResolving = true;
+        try {
+          return this._getOrCreateServiceInstance(
+            token,
+            Trace.traceCreation(false, CascadeEngine),
+          );
+        } finally {
+          this._cascadeResolving = false;
+        }
+      },
+      retire: (token) => this._retireUnit(token),
+      applyProvide: (token, descriptor, config) => {
+        this._services.set(token, descriptor, { config });
+        return this._services.uidOf(token)!;
+      },
+      applyProvideInstance: (token, instance, config) => {
+        this._services.set(token, instance, { config });
+        return this._services.uidOf(token)!;
+      },
+      applyUnprovide: (token) => {
+        this._services.delete(token);
+      },
+      recipeOf: (token) => {
+        const entry = this._services.entry(token);
+        if (entry === undefined) return undefined;
+        return entry.value instanceof SyncDescriptor ? entry.value : entry.recipe;
+      },
+      dependenciesOf: (recipe) =>
+        _util.getInstanceDependencies(recipe.ctor).map((dependency) => dependency.id),
+    };
+    this.cascade = new CascadeEngine(host, this, this._tree);
+  }
+
+  get cascadeDisposed(): boolean {
+    return this._disposed;
+  }
+
+  get cascadeDepth(): number {
+    return (this._parent?.cascadeDepth ?? -1) + 1;
+  }
+
+  private _ownerOf(id: ServiceIdentifier<any>): InstantiationService | undefined {
+    if (this._services.has(id)) {
+      return this;
+    }
+    return this._parent?._ownerOf(id);
+  }
+
+  invokeFunction<R, TS extends any[] = []>(
+    fn: (accessor: ServicesAccessor, ...args: TS) => R,
+    ...args: TS
+  ): R {
+    this._assertNotDisposed();
+    const _trace = Trace.traceInvocation(this._enableTracing, fn);
+    let done = false;
+    try {
+      const accessor: ServicesAccessor = {
+        get: <T>(id: ServiceIdentifier<T>): T => {
+          if (done) {
+            throw new Error(
+              'service accessor is only valid during the invocation of its target method',
+            );
+          }
+          const result = this._getOrCreateServiceInstance(id, _trace);
+          if (!result) {
+            this._throwIfStrict(`[invokeFunction] unknown service '${String(id)}'`, false);
+          }
+          return result;
+        },
+      };
+      return fn(accessor, ...args);
+    } finally {
+      done = true;
+      _trace.stop();
+    }
+  }
+
+  provide<T>(
+    id: ServiceIdentifier<T>,
+    instanceOrDescriptor: T | SyncDescriptor<T>,
+    options?: ProvideOptions,
+  ): ProvideHandle {
+    this._assertNotDisposed();
+    const core = this._provideCore(id, instanceOrDescriptor, options);
+    const entry = this._ledger.register(() => {
+      void core.dispose();
+    }, `provide:${String(id)}`);
+    this._provideEntries.set(id, { entry, core });
+    return {
+      get uid(): number {
+        return core.uid();
+      },
+      dispose: () => {
+        void entry.dispose();
+      },
+    };
+  }
+
+  provideAll(entries: ReadonlyArray<ProvideAllEntry>): void {
+    this._assertNotDisposed();
+    const changes: CascadeChange[] = [];
+    for (const { id, descriptor, options } of entries) {
+      this._releaseProvideEntry(id);
+      changes.push({
+        action: 'provide',
+        token: id,
+        descriptor,
+        activation: options?.activation,
+        config: options?.config,
+        reason: `provide ${String(id)}`,
+      });
+    }
+    this.cascade.submitAll(changes).catch(onUnexpectedError);
+    for (const { id } of entries) {
+      const uid = this._services.uidOf(id);
+      if (uid === undefined) {
+        continue;
+      }
+      const entry = this._ledger.register(() => {
+        if (this._services.uidOf(id) === uid) {
+          void this._unprovideCore(id);
+        }
+      }, `provide:${String(id)}`);
+      this._provideEntries.set(id, {
+        entry,
+        core: {
+          uid: () => uid,
+          dispose: () => {
+            if (this._services.uidOf(id) === uid) {
+              return this._unprovideCore(id);
+            }
+            return Promise.resolve();
+          },
+          release: () => {},
+        },
+      });
+    }
+  }
+
+  private _provideCore<T>(
+    id: ServiceIdentifier<T>,
+    instanceOrDescriptor: T | SyncDescriptor<T>,
+    options?: ProvideOptions,
+  ): TokenProvideCore {
+    this._releaseProvideEntry(id);
+
+    if (
+      !(instanceOrDescriptor instanceof SyncDescriptor) &&
+      this._services.get(id) === instanceOrDescriptor
+    ) {
+      this._services.set(id, instanceOrDescriptor);
+      const uid = this._services.uidOf(id)!;
+      return {
+        uid: () => uid,
+        dispose: () => {
+          if (this._services.uidOf(id) === uid) {
+            return this._unprovideCore(id);
+          }
+          return Promise.resolve();
+        },
+        release: () => {},
+      };
+    }
+
+    const beforeUid = this._services.uidOf(id);
+    let appliedUid: number | undefined;
+    const availability = this._services.onDidChange(id, ({ newUid }) => {
+      if (newUid !== undefined && newUid !== beforeUid) {
+        appliedUid ??= newUid;
+      }
+    });
+    const release = (): void => {
+      availability.dispose();
+    };
+    const change: CascadeChange =
+      instanceOrDescriptor instanceof SyncDescriptor
+        ? {
+            action: 'provide',
+            token: id,
+            descriptor: instanceOrDescriptor,
+            activation: options?.activation,
+            config: options?.config,
+            reason: `provide ${String(id)}`,
+          }
+        : {
+            action: 'provide',
+            token: id,
+            instance: instanceOrDescriptor,
+            config: options?.config,
+            reason: `provide ${String(id)}`,
+          };
+    this.cascade.submit(change).catch(onUnexpectedError);
+    return {
+      uid: () => {
+        if (appliedUid === undefined) {
+          throw new Error(
+            `provide of '${String(id)}' has not been applied yet (cascade in flight)`,
+          );
+        }
+        return appliedUid;
+      },
+      dispose: () => {
+        release();
+        if (appliedUid !== undefined && this._services.uidOf(id) === appliedUid) {
+          return this._unprovideCore(id);
+        }
+        return Promise.resolve();
+      },
+      release,
+    };
+  }
+
+  private _unprovideCore<T>(id: ServiceIdentifier<T>): Promise<void> {
+    if (this._disposed) {
+      return Promise.resolve();
+    }
+    this._releaseProvideEntry(id);
+    if (this._services.get(id) === undefined) {
+      return Promise.resolve();
+    }
+    return this.cascade
+      .submit({ action: 'unprovide', token: id, reason: `unprovide ${String(id)}` })
+      .catch((error: unknown) => {
+        onUnexpectedError(error);
+      });
+  }
+
+  unprovide<T>(id: ServiceIdentifier<T>): void {
+    void this._unprovideCore(id);
+  }
+
+  private _releaseProvideEntry(id: ServiceIdentifier<any>): void {
+    const prev = this._provideEntries.get(id);
+    if (prev !== undefined) {
+      this._provideEntries.delete(id);
+      prev.entry.release();
+      prev.core.release();
+    }
+  }
+
+  private _retireUnit<T>(id: ServiceIdentifier<T>): void | Promise<void> {
+    const instance = this._services.get(id);
+    if (instance === undefined || instance instanceof SyncDescriptor) {
+      return undefined;
+    }
+    this._services.unmaterialize(id);
+    const entry = this._instanceEntries.get(instance);
+    if (entry === undefined) {
+      return undefined;
+    }
+    this._instanceEntries.delete(instance);
+    const serviceInstance = instance as object;
+    this._edgeNodes.delete(serviceInstance);
+    this._tree.graph.removeInstance(serviceInstance);
+    return entry.dispose();
+  }
+
+  private _nextUnitUid = 0;
+
+  get fiberHost(): FiberHost {
+    return this._getFiberHost();
+  }
+
+  get collectionStore(): CollectionStore {
+    return this._collectionStore;
+  }
+
+  get ledger(): Ledger {
+    return this._ledger;
+  }
+
+  get cascadeTree(): CascadeTree {
+    return this._tree;
+  }
+
+  get children(): readonly InstantiationService[] {
+    return [...this._children];
+  }
+
+  servicesSnapshot(): { token: string; uid: number }[] {
+    const snapshot: { token: string; uid: number }[] = [];
+    this._services.forEach((id) => {
+      snapshot.push({
+        token: id.toString(),
+        uid: this._services.uidOf(id)!,
+      });
+    });
+    return snapshot;
+  }
+
+  findIdentifier(tokenString: string): ServiceIdentifier<unknown> | undefined {
+    let found: ServiceIdentifier<unknown> | undefined;
+    this._services.forEach((id) => {
+      if (found === undefined && id.toString() === tokenString) {
+        found = id;
+      }
+    });
+    return found;
+  }
+
+  anchorKernelEntry(disposer: Disposer, label: string): LedgerEntry {
+    return this._ledger.register(disposer, label);
+  }
+
+  anchorKernelFinalizer(disposer: Disposer, label: string): LedgerEntry {
+    return this._ledger.registerFinalizer(disposer, label);
+  }
+
+  private _getFiberHost(): FiberHost {
+    this._fiberHost ??= {
+      mintUid: () => ++this._root()._nextUnitUid,
+      provideToken: (id, descriptor, options) => this._provideCore(id, descriptor, options),
+      provideTokenInstance: <T>(id: ServiceIdentifier<T>, instance: T) =>
+        this._provideCore(id, instance, undefined),
+      tokenState: (id: ServiceIdentifier<any>) => {
+        const owner = this._ownerOf(id) ?? this;
+        return owner.cascade.stateOf(id);
+      },
+      updateToken: async (id, config, hasConfig) => {
+        const owner = this._ownerOf(id);
+        if (owner === undefined) {
+          throw new Error(`update of unregistered token '${String(id)}'`);
+        }
+        if (hasConfig) {
+          owner._services.setConfig(id, config);
+        }
+        await owner.cascade.update(id);
+      },
+      resolveTokenWhenAvailable: <T>(id: ServiceIdentifier<T>): Promise<T> =>
+        this.cascade.resolveWhenAvailable<T>(id),
+      resolveInstance: <T>(id: ServiceIdentifier<T>): T =>
+        this.invokeFunction((accessor) => accessor.get(id)),
+      materializedInstance: <T>(id: ServiceIdentifier<T>): T | undefined =>
+        this._materializedInstanceOf(id),
+      liveRef: <T>(id: ServiceIdentifier<T>): LiveRef<T> => this._liveRef(id),
+      recordInstanceEdge: (node: object | undefined, id: ServiceIdentifier<any>) => {
+        if (node === undefined) {
+          return;
+        }
+        const owner = this._ownerOf(id);
+        if (owner !== undefined) {
+          this._edgeNodes.add(node);
+          this.dependencyGraph.addEdge(node, { scope: owner, token: id }, 'instance');
+        }
+      },
+      collectionView: <T>(token: CollectionToken<T>): CollectionView<T> =>
+        this._collectionView(token),
+      addCollectionRecord: <T>(
+        token: CollectionToken<T>,
+        providerName: string,
+        providerBook: Ledger,
+        value: T,
+      ) =>
+        this._collectionStore.addRecord(
+          token,
+          this,
+          providerName,
+          this._scopePath(),
+          providerBook,
+          value,
+        ),
+      constructService: <T>(ctor: new (...args: any[]) => T, config: unknown): T => {
+        return this._createInstance(ctor, [], Trace.traceCreation(this._enableTracing, ctor), {
+          config,
+        });
+      },
+    };
+    return this._fiberHost;
+  }
+
+  private _materializedInstanceOf<T>(id: ServiceIdentifier<T>): T | undefined {
+    const value = this._services.get(id);
+    if (value !== undefined) {
+      return value instanceof SyncDescriptor ? undefined : (value as T);
+    }
+    return this._parent?._materializedInstanceOf(id);
+  }
+
+  private _liveRef<T>(id: ServiceIdentifier<T>): LiveRef<T> {
+    const change = new Emitter<void>();
+    const chain: InstantiationService[] = [this];
+    for (let c = this._parent; c !== undefined; c = c._parent) {
+      chain.push(c);
+    }
+    const subscriptions = chain.map((container) =>
+      container._services.onDidChange(id, () => {
+        change.fire();
+      }),
+    );
+    this._ledger.register(() => {
+      for (const subscription of subscriptions) {
+        subscription.dispose();
+      }
+      change.dispose();
+    }, `ref:${String(id)}`);
+    const current = (): T | undefined => this._materializedInstanceOf(id);
+    const ref: LiveRef<T> = {
+      get current(): T | undefined {
+        return current();
+      },
+      onDidChange: change.event,
+    };
+    return ref;
+  }
+
+  private _collectionView<T>(token: CollectionToken<T>): CollectionView<T> {
+    let view = this._collectionViews.get(token as CollectionToken<unknown>);
+    if (view === undefined) {
+      view = this._collectionStore.createView(token, this);
+      this._collectionViews.set(token as CollectionToken<unknown>, view);
+    }
+    return view as CollectionViewImpl<T>;
+  }
+
+  private _scopePath(): string {
+    const labels: string[] = [this.debugLabel ?? `#${this._tree.seqOf(this)}`];
+    for (
+      let c: InstantiationService | undefined = this._parent;
+      c !== undefined;
+      c = c._parent
+    ) {
+      labels.unshift(c.debugLabel ?? `#${this._tree.seqOf(c)}`);
+    }
+    return labels.join('/');
+  }
+
+  createInstance<T>(descriptor: SyncDescriptor<T>, ...rest: any[]): T;
+  createInstance<T>(ctor: new (...args: any[]) => T, ...rest: any[]): T;
+  createInstance<T>(
+    ctorOrDescriptor: SyncDescriptor<T> | (new (...args: any[]) => T),
+    ...rest: any[]
+  ): T {
+    this._assertNotDisposed();
+    let _trace: Trace;
+    let result: T;
+    if (ctorOrDescriptor instanceof SyncDescriptor) {
+      _trace = Trace.traceCreation(this._enableTracing, ctorOrDescriptor.ctor);
+      result = this._createInstance(
+        ctorOrDescriptor.ctor,
+        ctorOrDescriptor.staticArguments.concat(rest),
+        _trace,
+      );
+    } else {
+      _trace = Trace.traceCreation(this._enableTracing, ctorOrDescriptor);
+      result = this._createInstance(ctorOrDescriptor, rest, _trace);
+    }
+    _trace.stop();
+    return result;
+  }
+
+  createChild(services: ServiceCollection, store?: DisposableStore): IInstantiationService {
+    this._assertNotDisposed();
+    if (!(services instanceof ServiceCollection)) {
+      throw new TypeError(
+        'createChild requires a ServiceCollection instance (got something else)',
+      );
+    }
+    const child = this._createChildService(services);
+    this._children.add(child);
+    child._parentLedgerEntry = this._ledger.register(() => {
+      child.dispose();
+    }, 'child-instantiation');
+    store?.add(child);
+    return child;
+  }
+
+  protected _createChildService(services: ServiceCollection): InstantiationService {
+    return new InstantiationService(services, this._strict, this, this._enableTracing);
+  }
+
+  private _disposePromise: Promise<void> | undefined;
+
+  dispose(): void {
+    void this.disposeAsync();
+  }
+
+  disposeAsync(): Promise<void> {
+    this._disposePromise ??= this.disposeCore();
+    return this._disposePromise;
+  }
+
+  private disposeCore(): Promise<void> {
+    if (this._disposed) {
+      return Promise.resolve();
+    }
+    this._disposed = true;
+
+    const childTeardowns: Promise<void>[] = [];
+    let teardown: void | Promise<void> = undefined;
+    try {
+      for (const child of Array.from(this._children)) {
+        childTeardowns.push(child.disposeAsync());
+      }
+      this._children.clear();
+      teardown = this._ledger.teardown('scope-close');
+      this._services.dispose();
+      this.cascade.dispose();
+      for (const view of this._collectionViews.values()) {
+        view.dispose();
+      }
+      this._collectionViews.clear();
+      for (const node of this._edgeNodes) {
+        this._tree.graph.removeInstance(node);
+      }
+      this._edgeNodes.clear();
+      this._tree.graph.removeScope(this);
+    } finally {
+      this._children.clear();
+      this._parentLedgerEntry?.release();
+      this._parentLedgerEntry = undefined;
+      if (this._parent) {
+        this._parent._children.delete(this);
+      }
+    }
+    return Promise.all([...childTeardowns, Promise.resolve(teardown)]).then(() => undefined);
+  }
+
+  private _createInstance<T>(ctor: any, args: unknown[], _trace: Trace, unit?: {
+    id?: ServiceIdentifier<any>;
+    config?: unknown;
+  }): T {
+    const serviceDependencies = _util.getServiceDependencies(ctor).toSorted((a, b) => a.index - b.index);
+    const serviceArgs: unknown[] = [];
+    for (const dependency of serviceDependencies) {
+      const kind = dependency.kind ?? 'instance';
+      if (kind === 'collection') {
+        serviceArgs.push(this._collectionView(dependency.id as unknown as CollectionToken<unknown>));
+        continue;
+      }
+      if (kind === 'ref') {
+        serviceArgs.push(this._liveRef(dependency.id));
+        continue;
+      }
+        const service = this._getOrCreateServiceInstance(dependency.id, _trace);
+        if (!service) {
+          this._throwIfStrict(
+            `[createInstance] ${ctor.name} depends on UNKNOWN service ${String(dependency.id)}.`,
+            false,
+          );
+        }
+      serviceArgs.push(service);
+    }
+
+    const firstServiceArgPos =
+      serviceDependencies.length > 0 ? serviceDependencies[0]!.index : args.length;
+
+    if (args.length !== firstServiceArgPos) {
+      globalThis.console.trace(
+        `[createInstance] First service dependency of ${(ctor as { name?: string }).name} at position ${firstServiceArgPos + 1} conflicts with ${args.length} static arguments`,
+      );
+      const delta = firstServiceArgPos - args.length;
+      if (delta > 0) {
+        args = args.concat(Array.from({ length: delta }));
+      } else {
+        args = args.slice(0, firstServiceArgPos);
+      }
+    }
+
+    const finalArgs = args.concat(serviceArgs);
+    if (!isServiceRecipe(ctor)) {
+      return Reflect.construct<unknown[], T>(ctor, finalArgs);
+    }
+    const frame: ConstructionFrame = {
+      ctor,
+      config: unit?.config,
+      token: unit?.id,
+      host: this._getFiberHost(),
+    };
+    pushConstructionFrame(frame);
+    let instance: T;
+    try {
+      instance = Reflect.construct<unknown[], T>(ctor as new (...args: any[]) => T, finalArgs);
+    } finally {
+      popConstructionFrame();
+    }
+    bindServiceUnit(instance as UnitInternals & IDisposable, frame);
+    return instance;
+  }
+
+  protected _getOrCreateServiceInstance<T>(id: ServiceIdentifier<T>, _trace: Trace): T {
+    if (!this._cascadeResolving) {
+      if (this.cascade.isInFlight(id)) {
+        throw new CascadeConflictError(
+          String(id),
+          'token is inside an in-flight cascade transaction',
+        );
+      }
+      const failure = this.cascade.failureOf(id);
+      if (failure !== undefined) {
+        throw failure as Error;
+      }
+    }
+    const entry = this._getServiceInstanceOrDescriptor(id);
+
+    if (entry instanceof SyncDescriptor) {
+      const root = this._root();
+      if (root._inProgress.includes(id)) {
+        const path = [...root._inProgress, id].map(String);
+        throw new CyclicDependencyError(path);
+      }
+
+      return this._safeCreateAndCacheServiceInstance(id, entry, _trace.branch(id, true));
+    }
+
+    _trace.branch(id, false);
+    return entry as T;
+  }
+
+  private _safeCreateAndCacheServiceInstance<T>(
+    id: ServiceIdentifier<T>,
+    desc: SyncDescriptor<T>,
+    _trace: Trace,
+  ): T {
+    if (this._activeInstantiations.has(id)) {
+      throw new Error(`illegal state - RECURSIVELY instantiating service '${String(id)}'`);
+    }
+    this._activeInstantiations.add(id);
+    try {
+      return this._createAndCacheServiceInstance(id, desc, _trace);
+    } finally {
+      this._activeInstantiations.delete(id);
+    }
+  }
+
+  private _createAndCacheServiceInstance<T>(
+    id: ServiceIdentifier<T>,
+    desc: SyncDescriptor<T>,
+    _trace: Trace,
+  ): T {
+    type Triple = { id: ServiceIdentifier<any>; desc: SyncDescriptor<any>; _trace: Trace };
+    const graph = new Graph<Triple>(data => data.id.toString());
+
+    let cycleCount = 0;
+    const stack: Triple[] = [{ id, desc, _trace }];
+    const seen = new Set<string>();
+    while (stack.length > 0) {
+      const item = stack.pop()!;
+
+      if (seen.has(String(item.id))) {
+        continue;
+      }
+      seen.add(String(item.id));
+
+      graph.lookupOrInsertNode(item);
+
+      if (cycleCount++ > 1000) {
+        throw new CyclicDependencyError(graph);
+      }
+
+      for (const dependency of _util.getInstanceDependencies(item.desc.ctor)) {
+        const instanceOrDesc = this._getServiceInstanceOrDescriptor(dependency.id);
+        if (!instanceOrDesc) {
+          this._throwIfStrict(
+            `[createInstance] ${String(item.id)} depends on ${String(dependency.id)} which is NOT registered.`,
+            true,
+          );
+        }
+
+        this._globalGraph?.insertEdge(String(item.id), String(dependency.id));
+
+        if (instanceOrDesc instanceof SyncDescriptor) {
+          const d: Triple = {
+            id: dependency.id,
+            desc: instanceOrDesc,
+            _trace: item._trace.branch(dependency.id, true),
+          };
+          graph.insertEdge(item, d);
+          stack.push(d);
+        }
+      }
+    }
+
+    while (true) {
+      const roots = graph.roots();
+
+      if (roots.length === 0) {
+        if (!graph.isEmpty()) {
+          throw new CyclicDependencyError(graph);
+        }
+        break;
+      }
+
+      for (const { data } of roots) {
+        const instanceOrDesc = this._getServiceInstanceOrDescriptor(data.id);
+        if (instanceOrDesc instanceof SyncDescriptor) {
+          const instance = this._createServiceInstanceWithOwner(
+            data.id,
+            data.desc.ctor,
+            data.desc.staticArguments,
+            data._trace,
+          );
+          this._setCreatedServiceInstance(data.id, instance);
+        }
+        graph.removeNode(data);
+      }
+    }
+    return this._getServiceInstanceOrDescriptor(id) as T;
+  }
+
+  private _createServiceInstanceWithOwner<T>(
+    id: ServiceIdentifier<T>,
+    ctor: any,
+    args: ReadonlyArray<unknown> = [],
+    _trace: Trace,
+  ): T {
+    if (this._services.get(id) instanceof SyncDescriptor) {
+      return this._createServiceInstance(id, ctor, args, _trace);
+    }
+    if (this._parent) {
+      return this._parent._createServiceInstanceWithOwner(
+        id,
+        ctor,
+        args,
+        _trace,
+      );
+    }
+    throw new Error(`illegalState - creating UNKNOWN service instance ${ctor.name}`);
+  }
+
+  private _createServiceInstance<T>(
+    id: ServiceIdentifier<T>,
+    ctor: any,
+    args: ReadonlyArray<unknown> = [],
+    _trace: Trace,
+  ): T {
+    const root = this._root();
+    root._inProgress.push(id);
+    try {
+      const result = this._createInstance<T>(ctor, args.slice(), _trace, {
+        id,
+        config: this._services.configOf(id),
+      });
+      this.dependencyGraph.addInstance(result as object, this, id);
+      for (const dependency of _util.getServiceDependencies(ctor)) {
+        const kind = dependency.kind ?? 'instance';
+        if (kind === 'collection') {
+          this.dependencyGraph.addEdge(
+            result as object,
+            { scope: this, token: dependency.id },
+            'collection',
+          );
+          continue;
+        }
+        if (kind === 'ref') {
+          continue;
+        }
+        const owner = this._ownerOf(dependency.id);
+        if (owner !== undefined) {
+          this.dependencyGraph.addEdge(
+            result as object,
+            { scope: owner, token: dependency.id },
+            'instance',
+          );
+        }
+      }
+      const entry = this._ledger.register(() => {
+        this._instanceEntries.delete(result);
+        this.dependencyGraph.removeInstance(result as object);
+        if (isDisposable(result)) {
+          const out = result.dispose() as unknown as void | Promise<void>;
+          return out;
+        }
+        return undefined;
+      }, `service:${String(id)}`);
+      this._instanceEntries.set(result, entry);
+      this.cascade.observedMaterialization(id);
+      return result;
+    } finally {
+      const popIdx = root._inProgress.lastIndexOf(id);
+      if (popIdx >= 0) {
+        root._inProgress.splice(popIdx, 1);
+      }
+    }
+  }
+
+  private _setCreatedServiceInstance<T>(id: ServiceIdentifier<T>, instance: T): void {
+    if (this._services.get(id) instanceof SyncDescriptor) {
+      this._services.materialize(id, instance);
+    } else if (this._parent) {
+      this._parent._setCreatedServiceInstance(id, instance);
+    } else {
+      throw new Error(
+        `illegal state - setting UNKNOWN service instance '${String(id)}'`,
+      );
+    }
+  }
+
+  private _getServiceInstanceOrDescriptor<T>(
+    id: ServiceIdentifier<T>,
+  ): T | SyncDescriptor<T> | undefined {
+    const instanceOrDesc = this._services.get(id);
+    if (instanceOrDesc === undefined && this._parent) {
+      return this._parent._getServiceInstanceOrDescriptor(id);
+    }
+    return instanceOrDesc;
+  }
+
+  private _throwIfStrict(msg: string, printWarning: boolean): void {
+    if (printWarning) {
+      globalThis.console.warn(msg);
+    }
+    if (this._strict) {
+      throw new Error(msg);
+    }
+  }
+
+  private _root(): InstantiationService {
+    return this._parent?._root() ?? this;
+  }
+
+  private _assertNotDisposed(): void {
+    if (this._disposed) {
+      throw new Error('InstantiationService has been disposed');
+    }
+  }
+}

packages/agent-core-v2/src/_base/di/lifecycle.ts

@@ -0,0 +1,709 @@
+import { onUnexpectedError } from '../errors/unexpectedError';
+import { Ledger, type LedgerEntry } from '../lifecycle/ledger';
+
+export interface IDisposableDebugLabel {
+  readonly debugLabel?: string;
+}
+
+function disposableLabel(d: IDisposable): string {
+  const debugLabel = (d as IDisposableDebugLabel).debugLabel;
+  if (typeof debugLabel === 'string' && debugLabel.length > 0) {
+    return debugLabel;
+  }
+  return `disposable:${d.constructor?.name ?? 'anonymous'}`;
+}
+
+export interface IDisposableTracker {
+  trackDisposable(disposable: IDisposable): void;
+  setParent(child: IDisposable, parent: IDisposable | null): void;
+  markAsDisposed(disposable: IDisposable): void;
+  markAsSingleton(disposable: IDisposable): void;
+}
+
+interface DisposableInfo {
+  value: IDisposable;
+  source: string | null;
+  parent: IDisposable | null;
+  isSingleton: boolean;
+  idx: number;
+}
+
+export class DisposableTracker implements IDisposableTracker {
+  private static idx = 0;
+  private readonly livingDisposables = new Map<IDisposable, DisposableInfo>();
+
+  private getDisposableData(d: IDisposable): DisposableInfo {
+    let val = this.livingDisposables.get(d);
+    if (!val) {
+      val = {
+        parent: null,
+        source: null,
+        isSingleton: false,
+        value: d,
+        idx: DisposableTracker.idx++,
+      };
+      this.livingDisposables.set(d, val);
+    }
+    return val;
+  }
+
+  trackDisposable(d: IDisposable): void {
+    const data = this.getDisposableData(d);
+    data.source ??= new Error('Disposable tracking').stack ?? null;
+  }
+
+  setParent(child: IDisposable, parent: IDisposable | null): void {
+    this.getDisposableData(child).parent = parent;
+  }
+
+  markAsDisposed(x: IDisposable): void {
+    this.livingDisposables.delete(x);
+  }
+
+  markAsSingleton(d: IDisposable): void {
+    this.getDisposableData(d).isSingleton = true;
+  }
+
+  private getRootParent(
+    data: DisposableInfo,
+    cache: Map<DisposableInfo, DisposableInfo>,
+  ): DisposableInfo {
+    const cached = cache.get(data);
+    if (cached) return cached;
+    const result = data.parent
+      ? this.getRootParent(this.getDisposableData(data.parent), cache)
+      : data;
+    cache.set(data, result);
+    return result;
+  }
+
+  getTrackedDisposables(): IDisposable[] {
+    const cache = new Map<DisposableInfo, DisposableInfo>();
+    return [...this.livingDisposables.entries()]
+      .filter(
+        ([, v]) => v.source !== null && !this.getRootParent(v, cache).isSingleton,
+      )
+      .map(([k]) => k);
+  }
+}
+
+let disposableTracker: IDisposableTracker | null = null;
+
+export function setDisposableTracker(tracker: IDisposableTracker | null): void {
+  disposableTracker = tracker;
+}
+
+export function trackDisposable<T extends IDisposable>(x: T): T {
+  disposableTracker?.trackDisposable(x);
+  return x;
+}
+
+export function markAsDisposed(disposable: IDisposable): void {
+  disposableTracker?.markAsDisposed(disposable);
+}
+
+function setParentOfDisposable(
+  child: IDisposable,
+  parent: IDisposable | null,
+): void {
+  disposableTracker?.setParent(child, parent);
+}
+
+function setParentOfDisposables(
+  children: IDisposable[],
+  parent: IDisposable | null,
+): void {
+  if (!disposableTracker) return;
+  for (const child of children) {
+    disposableTracker.setParent(child, parent);
+  }
+}
+
+export function markAsSingleton<T extends IDisposable>(singleton: T): T {
+  disposableTracker?.markAsSingleton(singleton);
+  return singleton;
+}
+
+export interface IDisposable {
+  dispose(): void;
+}
+
+export function isDisposable<E>(thing: E): thing is E & IDisposable {
+  return (
+    typeof thing === 'object' &&
+    thing !== null &&
+    typeof (thing as unknown as IDisposable).dispose === 'function' &&
+    (thing as unknown as IDisposable).dispose.length === 0
+  );
+}
+
+export function dispose<T extends IDisposable>(disposable: T): T;
+export function dispose<T extends IDisposable>(
+  disposable: T | undefined,
+): T | undefined;
+export function dispose<T extends IDisposable, A extends Iterable<T> = Iterable<T>>(
+  disposables: A,
+): A;
+export function dispose<T extends IDisposable>(disposables: Array<T>): Array<T>;
+export function dispose<T extends IDisposable>(
+  disposables: ReadonlyArray<T>,
+): ReadonlyArray<T>;
+export function dispose<T extends IDisposable>(
+  arg: T | Iterable<T> | undefined,
+): unknown {
+  if (arg === undefined || arg === null) return arg;
+  if (isIterable<T>(arg)) {
+    const errors: unknown[] = [];
+    for (const d of arg) {
+      if (d) {
+        try {
+          d.dispose();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+    }
+
+    if (errors.length === 1) {
+      throw errors[0];
+    }
+    if (errors.length > 1) {
+      throw new AggregateError(
+        errors,
+        'Encountered errors while disposing of store',
+      );
+    }
+
+    return Array.isArray(arg) ? [] : arg;
+  }
+  (arg).dispose();
+  return arg;
+}
+
+function isIterable<T>(arg: unknown): arg is Iterable<T> {
+  return (
+    typeof arg === 'object' &&
+    arg !== null &&
+    typeof (arg as { [Symbol.iterator]?: unknown })[Symbol.iterator] === 'function'
+  );
+}
+
+export function disposeIfDisposable<T extends IDisposable | object>(
+  disposables: Array<T>,
+): Array<T> {
+  const disposableValues: IDisposable[] = [];
+  for (const d of disposables) {
+    if (isDisposable(d)) {
+      disposableValues.push(d);
+    }
+  }
+  dispose(disposableValues);
+  return [];
+}
+
+class FunctionDisposable implements IDisposable {
+  private _isDisposed = false;
+  private readonly _fn: () => void;
+
+  constructor(fn: () => void) {
+    this._fn = fn;
+    trackDisposable(this);
+  }
+
+  dispose(): void {
+    if (this._isDisposed) return;
+    this._isDisposed = true;
+    markAsDisposed(this);
+    this._fn();
+  }
+}
+
+export function toDisposable(fn: () => void): IDisposable {
+  return new FunctionDisposable(fn);
+}
+
+export function combinedDisposable(...disposables: IDisposable[]): IDisposable {
+  const parent = toDisposable(() => dispose(disposables));
+  setParentOfDisposables(disposables, parent);
+  return parent;
+}
+
+export class DisposableStore implements IDisposable {
+  private readonly _ledger = new Ledger('DisposableStore');
+  private readonly _entries = new Map<IDisposable, LedgerEntry>();
+  private _isDisposed = false;
+
+  constructor() {
+    trackDisposable(this);
+  }
+
+  get ledger(): Ledger {
+    return this._ledger;
+  }
+
+  add<T extends IDisposable>(d: T): T {
+    if ((d as unknown as DisposableStore) === this) {
+      throw new Error('Cannot register a disposable on itself!');
+    }
+    setParentOfDisposable(d, this);
+    if (this._isDisposed) {
+      d.dispose();
+      return d;
+    }
+    if (!this._entries.has(d)) {
+      this._entries.set(
+        d,
+        this._ledger.register(() => {
+          d.dispose();
+        }, disposableLabel(d)),
+      );
+    }
+    return d;
+  }
+
+  delete<T extends IDisposable>(d: T): void {
+    if (this._isDisposed) return;
+    if ((d as unknown as DisposableStore) === this) {
+      throw new Error('Cannot dispose a disposable on itself!');
+    }
+    const entry = this._entries.get(d);
+    if (entry) {
+      this._entries.delete(d);
+      entry.release();
+    }
+    d.dispose();
+  }
+
+  deleteAndLeak<T extends IDisposable>(d: T): void {
+    if (this._isDisposed) return;
+    const entry = this._entries.get(d);
+    if (entry) {
+      this._entries.delete(d);
+      entry.release();
+      setParentOfDisposable(d, null);
+    }
+  }
+
+  clear(): void {
+    if (this._entries.size === 0) return;
+    try {
+      void this._ledger.clear('scope-close');
+    } finally {
+      this._entries.clear();
+    }
+  }
+
+  dispose(): void {
+    if (this._isDisposed) return;
+    this._isDisposed = true;
+    markAsDisposed(this);
+    try {
+      void this._ledger.teardown('scope-close');
+    } finally {
+      this._entries.clear();
+    }
+  }
+
+  get isDisposed(): boolean {
+    return this._isDisposed;
+  }
+
+  assertNotDisposed(): void {
+    if (this._isDisposed) {
+      onUnexpectedError(new Error('Object disposed'));
+    }
+  }
+}
+
+export abstract class Disposable implements IDisposable {
+  protected readonly _store = new DisposableStore();
+
+  constructor() {
+    trackDisposable(this);
+    setParentOfDisposable(this._store, this);
+  }
+
+  protected _register<T extends IDisposable>(d: T): T {
+    if ((d as unknown as Disposable) === this) {
+      throw new Error('Cannot register a disposable on itself!');
+    }
+    return this._store.add(d);
+  }
+
+  dispose(): void {
+    markAsDisposed(this);
+    this._store.dispose();
+  }
+}
+
+export namespace Disposable {
+  export const None: IDisposable = Object.freeze({
+    dispose(): void {},
+  });
+}
+
+export class MutableDisposable<T extends IDisposable> implements IDisposable {
+  private readonly _ledger = new Ledger('MutableDisposable');
+  private _entry: LedgerEntry | undefined;
+  private _value: T | undefined;
+  private _isDisposed = false;
+
+  constructor() {
+    trackDisposable(this);
+  }
+
+  get value(): T | undefined {
+    return this._isDisposed ? undefined : this._value;
+  }
+
+  set value(value: T | undefined) {
+    if (this._isDisposed) {
+      if (value !== undefined) {
+        value.dispose();
+      }
+      return;
+    }
+    if (this._value === value) return;
+    this._entry?.release();
+    this._entry = undefined;
+    this._value?.dispose();
+    if (value) setParentOfDisposable(value, this);
+    this._value = value;
+    if (value) {
+      this._entry = this._ledger.register(() => {
+        value.dispose();
+      }, disposableLabel(value));
+    }
+  }
+
+  dispose(): void {
+    if (this._isDisposed) return;
+    this._isDisposed = true;
+    markAsDisposed(this);
+    const entry = this._entry;
+    const prev = this._value;
+    this._entry = undefined;
+    this._value = undefined;
+    entry?.release();
+    void this._ledger.teardown('scope-close');
+    if (prev !== undefined) {
+      prev.dispose();
+    }
+  }
+
+  clear(): void {
+    if (this._isDisposed) return;
+    this.value = undefined;
+  }
+
+  clearAndLeak(): T | undefined {
+    if (this._isDisposed) return undefined;
+    const prev = this._value;
+    this._value = undefined;
+    this._entry?.release();
+    this._entry = undefined;
+    if (prev !== undefined) setParentOfDisposable(prev, null);
+    return prev;
+  }
+}
+
+export class MandatoryMutableDisposable<T extends IDisposable> implements IDisposable {
+  private readonly _disposable = new MutableDisposable<T>();
+  private _isDisposed = false;
+
+  constructor(initialValue: T) {
+    this._disposable.value = initialValue;
+  }
+
+  get value(): T {
+    return this._disposable.value!;
+  }
+
+  set value(value: T) {
+    if (this._isDisposed || value === this._disposable.value) return;
+    this._disposable.value = value;
+  }
+
+  dispose(): void {
+    if (this._isDisposed) return;
+    this._isDisposed = true;
+    this._disposable.dispose();
+  }
+}
+
+export class RefCountedDisposable {
+  private _counter = 1;
+
+  constructor(private readonly _disposable: IDisposable) {}
+
+  acquire(): this {
+    this._counter += 1;
+    return this;
+  }
+
+  release(): this {
+    this._counter -= 1;
+    if (this._counter === 0) {
+      this._disposable.dispose();
+    }
+    return this;
+  }
+}
+
+export interface IReference<T> extends IDisposable {
+  readonly object: T;
+}
+
+export abstract class ReferenceCollection<T> {
+  private readonly references = new Map<
+    string,
+    { readonly object: T; counter: number }
+  >();
+
+  acquire(key: string, ...args: unknown[]): IReference<T> {
+    let reference = this.references.get(key);
+    if (!reference) {
+      reference = {
+        counter: 0,
+        object: this.createReferencedObject(key, ...args),
+      };
+      this.references.set(key, reference);
+    }
+
+    const { object } = reference;
+    let disposed = false;
+    const dispose = () => {
+      if (disposed) return;
+      disposed = true;
+      reference.counter -= 1;
+      if (reference.counter === 0) {
+        this.destroyReferencedObject(key, reference.object);
+        this.references.delete(key);
+      }
+    };
+
+    reference.counter += 1;
+    return { object, dispose };
+  }
+
+  protected abstract createReferencedObject(key: string, ...args: unknown[]): T;
+  protected abstract destroyReferencedObject(key: string, object: T): void;
+}
+
+export class AsyncReferenceCollection<T> {
+  constructor(private readonly referenceCollection: ReferenceCollection<Promise<T>>) {}
+
+  async acquire(key: string, ...args: unknown[]): Promise<IReference<T>> {
+    const ref = this.referenceCollection.acquire(key, ...args);
+
+    try {
+      const object = await ref.object;
+      return {
+        object,
+        dispose: () => { ref.dispose(); },
+      };
+    } catch (error) {
+      ref.dispose();
+      throw error;
+    }
+  }
+}
+
+export class ImmortalReference<T> implements IReference<T> {
+  constructor(public readonly object: T) {}
+  dispose(): void {}
+}
+
+export class DisposableMap<K, V extends IDisposable = IDisposable>
+  implements IDisposable
+{
+  private readonly _store: Map<K, V>;
+  private _isDisposed = false;
+
+  constructor(store: Map<K, V> = new Map<K, V>()) {
+    this._store = store;
+    trackDisposable(this);
+  }
+
+  dispose(): void {
+    if (this._isDisposed) return;
+    this._isDisposed = true;
+    markAsDisposed(this);
+    this.clearAndDisposeAll();
+  }
+
+  clearAndDisposeAll(): void {
+    if (this._store.size === 0) return;
+    try {
+      dispose(this._store.values());
+    } finally {
+      this._store.clear();
+    }
+  }
+
+  has(key: K): boolean {
+    return this._store.has(key);
+  }
+
+  get size(): number {
+    return this._store.size;
+  }
+
+  get(key: K): V | undefined {
+    return this._store.get(key);
+  }
+
+  set(key: K, value: V, skipDisposeOnOverwrite = false): void {
+    if (this._isDisposed) {
+      console.warn(
+        new Error(
+          'Trying to add a disposable to a DisposableMap that has already been disposed of. The added object will be leaked!',
+        ).stack,
+      );
+      return;
+    }
+    if (!skipDisposeOnOverwrite) {
+      const prev = this._store.get(key);
+      if (prev !== undefined && prev !== value) {
+        prev.dispose();
+      }
+    }
+    this._store.set(key, value);
+    setParentOfDisposable(value, this);
+  }
+
+  deleteAndDispose(key: K): void {
+    const value = this._store.get(key);
+    if (value !== undefined) {
+      value.dispose();
+    }
+    this._store.delete(key);
+  }
+
+  deleteAndLeak(key: K): V | undefined {
+    const value = this._store.get(key);
+    if (value !== undefined) setParentOfDisposable(value, null);
+    this._store.delete(key);
+    return value;
+  }
+
+  keys(): IterableIterator<K> {
+    return this._store.keys();
+  }
+
+  values(): IterableIterator<V> {
+    return this._store.values();
+  }
+
+  [Symbol.iterator](): IterableIterator<[K, V]> {
+    return this._store[Symbol.iterator]();
+  }
+}
+
+export class DisposableSet<V extends IDisposable = IDisposable>
+  implements IDisposable
+{
+  private readonly _store: Set<V>;
+  private _isDisposed = false;
+
+  constructor(store: Set<V> = new Set<V>()) {
+    this._store = store;
+    trackDisposable(this);
+  }
+
+  dispose(): void {
+    if (this._isDisposed) return;
+    this._isDisposed = true;
+    markAsDisposed(this);
+    this.clearAndDisposeAll();
+  }
+
+  clearAndDisposeAll(): void {
+    if (this._store.size === 0) return;
+    try {
+      dispose(this._store.values());
+    } finally {
+      this._store.clear();
+    }
+  }
+
+  has(value: V): boolean {
+    return this._store.has(value);
+  }
+
+  get size(): number {
+    return this._store.size;
+  }
+
+  add(value: V): void {
+    if (this._isDisposed) {
+      console.warn(
+        new Error(
+          'Trying to add a disposable to a DisposableSet that has already been disposed of. The added object will be leaked!',
+        ).stack,
+      );
+      return;
+    }
+    this._store.add(value);
+    setParentOfDisposable(value, this);
+  }
+
+  deleteAndDispose(value: V): void {
+    if (this._store.delete(value)) {
+      value.dispose();
+    }
+  }
+
+  deleteAndLeak(value: V): V | undefined {
+    if (this._store.delete(value)) {
+      setParentOfDisposable(value, null);
+      return value;
+    }
+    return undefined;
+  }
+
+  values(): IterableIterator<V> {
+    return this._store.values();
+  }
+
+  [Symbol.iterator](): IterableIterator<V> {
+    return this._store[Symbol.iterator]();
+  }
+}
+
+export function disposeOnReturn(fn: (store: DisposableStore) => void): void {
+  const store = new DisposableStore();
+  try {
+    fn(store);
+  } finally {
+    store.dispose();
+  }
+}
+
+export function thenIfNotDisposed<T>(
+  promise: Promise<T>,
+  then: (result: T) => void,
+): IDisposable {
+  let disposed = false;
+  void promise.then((result) => {
+    if (disposed) return;
+    then(result);
+  });
+  return toDisposable(() => {
+    disposed = true;
+  });
+}
+
+export function thenRegisterOrDispose<T extends IDisposable>(
+  promise: Promise<T>,
+  store: DisposableStore,
+): Promise<T> {
+  return promise.then((disposable) => {
+    if (store.isDisposed) {
+      disposable.dispose();
+    } else {
+      store.add(disposable);
+    }
+    return disposable;
+  });
+}

packages/agent-core-v2/src/_base/di/scope.ts

@@ -0,0 +1,300 @@
+import { BugIndicatingError } from '../errors/errors';
+import { SyncDescriptor } from './descriptors';
+import { ScopeActivation, type ProvideAllEntry } from './instantiation';
+import type { ServiceIdentifier, ServicesAccessor, IInstantiationService } from './instantiation';
+import { InstantiationService } from './instantiationService';
+import { DisposableStore, type IDisposable } from './lifecycle';
+import { Ledger, type LedgerEntry } from '../lifecycle/ledger';
+import { ServiceCollection } from './serviceCollection';
+import { watchScopeUnits } from './scopeUnits';
+
+export { ScopeActivation };
+
+export type ScopeKind = string;
+
+let _scopeTopology: readonly string[] | undefined;
+
+export function setScopeTopology(kinds: readonly string[]): void {
+  if (_scopeTopology === undefined) {
+    _scopeTopology = [...kinds];
+    return;
+  }
+  if (
+    _scopeTopology.length === kinds.length &&
+    _scopeTopology.every((kind, index) => kind === kinds[index])
+  ) {
+    return;
+  }
+  throw new BugIndicatingError(
+    `scope topology already declared as [${_scopeTopology.join(', ')}]; cannot redeclare as [${kinds.join(', ')}]`,
+  );
+}
+
+export interface ScopedEntry {
+  readonly scope: ScopeKind;
+  readonly id: ServiceIdentifier<unknown>;
+  readonly descriptor: SyncDescriptor<unknown>;
+  readonly domain: string;
+  readonly activation: ScopeActivation;
+}
+
+const _scopedRegistry: ScopedEntry[] = [];
+
+function findScopedEntryIndex(scope: ScopeKind, id: ServiceIdentifier<unknown>): number {
+  return _scopedRegistry.findIndex((entry) => entry.scope === scope && entry.id === id);
+}
+
+export function registerScopedService<T>(
+  scope: ScopeKind,
+  id: ServiceIdentifier<T>,
+  ctor: new (...args: any[]) => T,
+  activation: ScopeActivation = ScopeActivation.OnScopeCreated,
+  domain: string = 'unknown',
+): void {
+  const existing = findScopedEntryIndex(scope, id as ServiceIdentifier<unknown>);
+  if (existing !== -1) {
+    throw new BugIndicatingError(
+      `duplicate scoped service registration for '${String(id)}' in scope '${scope}' (registered domain '${_scopedRegistry[existing]?.domain}', attempted domain '${domain}'); use overrideScopedService for intentional replacement`,
+    );
+  }
+  const descriptor = new SyncDescriptor<T>(ctor);
+  _scopedRegistry.push({
+    scope,
+    id: id as ServiceIdentifier<unknown>,
+    descriptor: descriptor as SyncDescriptor<unknown>,
+    domain,
+    activation,
+  });
+}
+
+export function overrideScopedService<T>(
+  scope: ScopeKind,
+  id: ServiceIdentifier<T>,
+  ctor: new (...args: any[]) => T,
+  activation: ScopeActivation = ScopeActivation.OnScopeCreated,
+  domain: string = 'unknown',
+): void {
+  const index = findScopedEntryIndex(scope, id as ServiceIdentifier<unknown>);
+  if (index === -1) {
+    throw new BugIndicatingError(
+      `overrideScopedService found no registration for '${String(id)}' in scope '${scope}' (domain '${domain}'); use registerScopedService for the initial registration`,
+    );
+  }
+  const descriptor = new SyncDescriptor<T>(ctor);
+  _scopedRegistry[index] = {
+    scope,
+    id: id as ServiceIdentifier<unknown>,
+    descriptor: descriptor as SyncDescriptor<unknown>,
+    domain,
+    activation,
+  };
+}
+
+export function getScopedServiceDescriptors(scope: ScopeKind): ReadonlyArray<ScopedEntry> {
+  return _scopedRegistry.filter((entry) => entry.scope === scope);
+}
+
+export function _clearScopedRegistryForTests(): void {
+  _scopedRegistry.length = 0;
+}
+
+export type ScopeSeed = ReadonlyArray<
+  readonly [ServiceIdentifier<any>, unknown]
+>;
+
+export interface ScopeOptions {
+  readonly id?: string;
+  readonly seeds?: ScopeSeed;
+  readonly configureContainer?: (container: InstantiationService) => void;
+}
+
+export interface IScopeHandle<K extends ScopeKind = ScopeKind> {
+  readonly id: string;
+  readonly kind: K;
+  readonly accessor: ServicesAccessor;
+  dispose(): void | Promise<void>;
+}
+
+export type IAppScopeHandle = IScopeHandle<'app'>;
+export type ISessionScopeHandle = IScopeHandle<'session'>;
+export type IAgentScopeHandle = IScopeHandle<'agent'>;
+
+function buildCollection(seeds?: ScopeSeed): ServiceCollection {
+  const collection = new ServiceCollection();
+  if (seeds) {
+    for (const [id, value] of seeds) {
+      collection.set(id, value);
+    }
+  }
+  return collection;
+}
+
+function provideScopeServices(
+  instantiation: IInstantiationService,
+  kind: ScopeKind,
+  collection: ServiceCollection,
+): void {
+  const entries: ProvideAllEntry[] = [];
+  for (const entry of _scopedRegistry) {
+    if (entry.scope !== kind || collection.get(entry.id) !== undefined) {
+      continue;
+    }
+    entries.push({
+      id: entry.id,
+      descriptor: entry.descriptor,
+      options: {
+        activation: entry.activation === ScopeActivation.OnDemand ? 'ondemand' : 'eager',
+      },
+    });
+  }
+  instantiation.provideAll(entries);
+}
+
+export function createScopedChildHandle(
+  parent: IInstantiationService,
+  kind: ScopeKind,
+  id: string,
+  options: ScopeOptions = {},
+): IScopeHandle {
+  const collection = buildCollection(options.seeds);
+  const child = parent.createChild(collection);
+  (child as InstantiationService).debugLabel = id;
+  const engine = (child as InstantiationService).cascade;
+  engine.suspendActivation();
+  try {
+    watchScopeUnits(child as InstantiationService, kind);
+    options.configureContainer?.(child as InstantiationService);
+    provideScopeServices(child, kind, collection);
+  } catch (error) {
+    child.dispose();
+    throw error;
+  } finally {
+    engine.resumeActivation();
+  }
+  const accessor: ServicesAccessor = {
+    get: <T>(serviceId: ServiceIdentifier<T>): T =>
+      child.invokeFunction((a) => a.get(serviceId)),
+  };
+  return { id, kind, accessor, dispose: () => child.disposeAsync() };
+}
+
+export class Scope implements IDisposable {
+  readonly children = new Map<string, Scope>();
+  readonly accessor: ServicesAccessor;
+
+  private readonly _store = new DisposableStore();
+  private readonly _ledger: Ledger;
+  private _ledgerEntry: LedgerEntry | undefined;
+  private _disposed = false;
+
+  private constructor(
+    readonly id: string,
+    readonly kind: ScopeKind,
+    readonly instantiation: IInstantiationService,
+    private readonly _parent?: Scope,
+  ) {
+    this._ledger = new Ledger(`scope:${id}`);
+    this._ledger.register(() => {
+      this.instantiation.dispose();
+    }, 'instantiation');
+    this._ledger.register(() => {
+      this._store.dispose();
+    }, 'store');
+    this.accessor = {
+      get: <T>(serviceId: ServiceIdentifier<T>): T =>
+        instantiation.invokeFunction((a) => a.get(serviceId)),
+    };
+  }
+
+  get ledger(): Ledger {
+    return this._ledger;
+  }
+
+  static createApp(options: ScopeOptions = {}): Scope {
+    const kind: ScopeKind = 'app';
+    const collection = buildCollection(options.seeds);
+    const instantiation = new InstantiationService(collection, true);
+    instantiation.debugLabel = options.id ?? 'app';
+    instantiation.cascade.suspendActivation();
+    try {
+      watchScopeUnits(instantiation, kind);
+      options.configureContainer?.(instantiation);
+      provideScopeServices(instantiation, kind, collection);
+    } catch (error) {
+      instantiation.dispose();
+      throw error;
+    } finally {
+      instantiation.cascade.resumeActivation();
+    }
+    return new Scope(options.id ?? 'app', kind, instantiation);
+  }
+
+  private _assertNotDisposed(): void {
+    if (this._disposed) {
+      throw new Error(`Scope '${this.id}' has been disposed`);
+    }
+  }
+
+  createChild(kind: ScopeKind, id: string, options: ScopeOptions = {}): Scope {
+    this._assertNotDisposed();
+    if (_scopeTopology !== undefined) {
+      const parentIndex = _scopeTopology.indexOf(this.kind);
+      const childIndex = _scopeTopology.indexOf(kind);
+      if (parentIndex === -1 || childIndex === -1 || childIndex <= parentIndex) {
+        throw new Error(
+          `child scope kind '${kind}' must be greater than parent kind '${this.kind}' in the declared scope topology`,
+        );
+      }
+    }
+    if (this.children.has(id)) {
+      throw new Error(`Scope '${this.id}' already has a child with id '${id}'`);
+    }
+    const collection = buildCollection(options.seeds);
+    const childInstantiation = this.instantiation.createChild(collection);
+    (childInstantiation as InstantiationService).debugLabel = id;
+    const engine = (childInstantiation as InstantiationService).cascade;
+    engine.suspendActivation();
+    try {
+      watchScopeUnits(childInstantiation as InstantiationService, kind);
+      options.configureContainer?.(childInstantiation as InstantiationService);
+      provideScopeServices(childInstantiation, kind, collection);
+    } catch (error) {
+      childInstantiation.dispose();
+      throw error;
+    } finally {
+      engine.resumeActivation();
+    }
+    const child = new Scope(id, kind, childInstantiation, this);
+    this.children.set(id, child);
+    child._ledgerEntry = this._ledger.register(() => {
+      child.dispose();
+    }, `scope:${id}`);
+    return child;
+  }
+
+  toHandle(): IScopeHandle {
+    return { id: this.id, kind: this.kind, accessor: this.accessor, dispose: () => this.dispose() };
+  }
+
+  dispose(): void {
+    if (this._disposed) {
+      return;
+    }
+    this._disposed = true;
+
+    this._ledgerEntry?.release();
+    this._ledgerEntry = undefined;
+    try {
+      void this._ledger.teardown('scope-close');
+    } finally {
+      this.children.clear();
+      if (this._parent) {
+        this._parent.children.delete(this.id);
+      }
+    }
+  }
+}
+
+export function createAppScope(options: ScopeOptions = {}): Scope {
+  return Scope.createApp(options);
+}

packages/agent-core-v2/src/_base/di/scopeUnits.ts

@@ -0,0 +1,110 @@
+import { onUnexpectedError } from '../errors/unexpectedError';
+import type { IDisposable } from './lifecycle';
+import { Ledger, type LedgerEntry } from '../lifecycle/ledger';
+import type { StoredRecord } from './collection';
+import {
+  FiberRuntime,
+  isClassRecipe,
+  ScopeUnits,
+  type EffectBody,
+  type ServiceRecipe,
+} from './fiber';
+import type { InstantiationService } from './instantiationService';
+import type { ScopeKind } from './scope';
+
+export function watchScopeUnits(container: InstantiationService, kind: ScopeKind): void {
+  if (container.cascadeDisposed) {
+    return;
+  }
+  const token = ScopeUnits(kind);
+  const host = container.fiberHost;
+  const view = host.collectionView(token);
+  const foldLedger = new Ledger(`scope-units:${kind}`);
+  container.anchorKernelEntry((reason) => foldLedger.teardown(reason), `scope-units:${kind}`);
+
+  const materialized = new Map<number, () => void | Promise<void>>();
+
+  const materialize = (record: StoredRecord): void => {
+    const recipe = record.value as ServiceRecipe;
+    const name = record.providerName;
+    const unitLedger = new Ledger(`scope-units:${kind}:${name}`);
+    try {
+      if (isClassRecipe(recipe)) {
+        const instance = host.constructService(recipe, undefined) as Partial<IDisposable>;
+        unitLedger.register(() => {
+          return instance.dispose?.();
+        }, `unit:${name}`);
+      } else {
+        const facade = new FiberRuntime(
+          host,
+          unitLedger,
+          name,
+          undefined,
+          undefined,
+          new Set(recipe.inject ?? []),
+          undefined,
+        );
+        const out =
+          typeof recipe === 'function'
+            ? recipe(facade, undefined)
+            : recipe.apply(facade, undefined);
+        unitLedger.effect((() => out) as EffectBody, `effect:${name}`);
+      }
+    } catch (error) {
+      void unitLedger.teardown('unload');
+      onUnexpectedError(error);
+      return;
+    }
+
+    let retracted = false;
+    let providerEntry: LedgerEntry | undefined;
+    const retract = (): void | Promise<void> => {
+      if (retracted) {
+        return undefined;
+      }
+      retracted = true;
+      providerEntry?.release();
+      providerEntry = undefined;
+      materialized.delete(record.id);
+      return unitLedger.teardown('unload');
+    };
+    if (!record.providerBook.isActive) {
+      void retract();
+      return;
+    }
+    providerEntry = record.providerBook.register(() => {
+      void retract();
+    }, `scope-units:${kind}`);
+    foldLedger.register(() => {
+      return retract();
+    }, `record:${name}`);
+    materialized.set(record.id, retract);
+  };
+
+  const reconcile = (): void => {
+    if (!foldLedger.isActive) {
+      return;
+    }
+    const records = container.collectionStore.storedRecordsFor(token, container);
+    const seen = new Set<number>();
+    for (const record of records) {
+      seen.add(record.id);
+      if (!materialized.has(record.id)) {
+        materialize(record);
+      }
+    }
+    for (const [id, retract] of Array.from(materialized)) {
+      if (!seen.has(id)) {
+        void retract();
+      }
+    }
+  };
+
+  const subscription = view.onDidChange(() => {
+    reconcile();
+  });
+  foldLedger.register(() => {
+    subscription.dispose();
+  }, 'view-subscription');
+  reconcile();
+}

packages/agent-core-v2/src/_base/di/service.ts

@@ -0,0 +1,138 @@
+import type { Emitter } from '../event';
+import type { EffectBody } from '../lifecycle/disposer';
+import type { Ledger } from '../lifecycle/ledger';
+import type { CollectionToken } from './collection';
+import {
+  currentConstruction,
+  FiberProtocolError,
+  FiberState,
+  PendingFiberHandle,
+  SERVICE_MARK,
+  type BufferedOp,
+  type Fiber,
+  type FiberHandle,
+  type FiberProvideOptions,
+  type FiberRuntime,
+  type RecipeStatics,
+  type ServiceClassRecipe,
+  type ServiceRecipe,
+  type UnitInternals,
+} from './fiber';
+import type { ServiceIdentifier, LiveRef } from './instantiation';
+import { Disposable } from './lifecycle';
+
+export abstract class Service extends Disposable implements Fiber, UnitInternals {
+  private __unitBuffer: BufferedOp[] | null;
+  private __unitRuntime: FiberRuntime | undefined;
+
+  readonly name: string;
+  readonly state: FiberState = FiberState.Active;
+  readonly config: unknown;
+
+  constructor() {
+    super();
+    const frame = currentConstruction();
+    if (
+      frame !== undefined &&
+      frame.ctor === (new.target as unknown as new (...args: any[]) => any)
+    ) {
+      this.__unitBuffer = [];
+      this.config = frame.config;
+    } else {
+      this.__unitBuffer = null;
+      this.config = undefined;
+    }
+    this.name = (this.constructor as any).name || 'anonymous';
+  }
+
+  provide<T>(
+    id: ServiceIdentifier<T>,
+    recipe: ServiceClassRecipe,
+    opts?: FiberProvideOptions,
+  ): FiberHandle<T>;
+  provide<T>(id: ServiceIdentifier<T>, instance: T): FiberHandle<T>;
+  provide(recipe: ServiceRecipe, opts?: FiberProvideOptions): FiberHandle;
+  provide<T>(token: CollectionToken<T>, value: T): FiberHandle;
+  provide(
+    first: any,
+    second?: any,
+    third?: FiberProvideOptions,
+  ): FiberHandle {
+    if (this.__unitBuffer !== null) {
+      const pending = new PendingFiberHandle(this._pendingName(first));
+      this.__unitBuffer.push((runtime) => {
+        pending.attach(runtime.provide(first, second, third));
+      });
+      return pending;
+    }
+    return this._runtime().provide(first, second, third);
+  }
+
+  effect(body: EffectBody, label?: string): FiberHandle {
+    if (this.__unitBuffer !== null) {
+      const pending = new PendingFiberHandle(label ?? `effect:${this.name}`);
+      this.__unitBuffer.push((runtime) => {
+        pending.attach(runtime.effect(body, label));
+      });
+      return pending;
+    }
+    return this._runtime().effect(body, label);
+  }
+
+  on(event: string | Emitter<any>, handler: (e: any) => void): FiberHandle {
+    const label = typeof event === 'string' ? `on:${event}` : 'on:emitter';
+    if (this.__unitBuffer !== null) {
+      const pending = new PendingFiberHandle(label);
+      this.__unitBuffer.push((runtime) => {
+        pending.attach(runtime.on(event, handler));
+      });
+      return pending;
+    }
+    return this._runtime().on(event, handler);
+  }
+
+  get<T>(id: ServiceIdentifier<T>): T {
+    return this._runtime().get(id);
+  }
+
+  ref<T>(id: ServiceIdentifier<T>): LiveRef<T> {
+    return this._runtime().ref(id);
+  }
+
+  get unitBook(): Ledger {
+    return this._store.ledger;
+  }
+
+  takeUnitBuffer(): BufferedOp[] | null {
+    const buffer = this.__unitBuffer;
+    this.__unitBuffer = null;
+    return buffer;
+  }
+
+  setUnitRuntime(runtime: FiberRuntime): void {
+    this.__unitRuntime = runtime;
+  }
+
+  private _runtime(): FiberRuntime {
+    if (this.__unitRuntime === undefined) {
+      if (this.__unitBuffer !== null) {
+        throw new FiberProtocolError(
+          `unit '${this.name}': get/ref/provide reads are not available during construction — declare dependencies as constructor parameters (构造期只写不读)`,
+        );
+      }
+      throw new FiberProtocolError(
+        `unit '${this.name}': no unit runtime is bound — a Service created by manual \`new\` has no capabilities; construct it through the container`,
+      );
+    }
+    return this.__unitRuntime;
+  }
+
+  private _pendingName(first: any): string {
+    if (typeof first === 'function') {
+      return (first as RecipeStatics).name ?? String(first);
+    }
+    return this.name;
+  }
+}
+
+(Service.prototype as unknown as Record<symbol, unknown>)[SERVICE_MARK] = true;

packages/agent-core-v2/src/_base/di/serviceCollection.ts

@@ -0,0 +1,144 @@
+import { Emitter } from '../event';
+import { SyncDescriptor } from './descriptors';
+import type { ServiceIdentifier } from './instantiation';
+import type { IDisposable } from './lifecycle';
+
+export interface ServiceCollectionEntry<T = unknown> {
+  readonly value: T | SyncDescriptor<T>;
+  readonly uid: number;
+  readonly config?: unknown;
+  readonly recipe?: SyncDescriptor<T>;
+}
+
+export interface AvailabilityChange {
+  readonly oldUid: number | undefined;
+  readonly newUid: number | undefined;
+}
+
+export class ServiceCollection {
+  private readonly _entries = new Map<ServiceIdentifier<any>, ServiceCollectionEntry<any>>();
+  private readonly _emitters = new Map<
+    ServiceIdentifier<any>,
+    Emitter<AvailabilityChange>
+  >();
+  private _nextUid = 0;
+
+  constructor(
+    ...entries: ReadonlyArray<readonly [ServiceIdentifier<any>, unknown]>
+  ) {
+    for (const [id, value] of entries) {
+      this.set(id, value);
+    }
+  }
+
+  set<T>(
+    id: ServiceIdentifier<T>,
+    instanceOrDescriptor: T | SyncDescriptor<T>,
+    options?: { readonly config?: unknown },
+  ): T | SyncDescriptor<T> | undefined {
+    const prev = this._entries.get(id);
+    const uid = ++this._nextUid;
+    this._entries.set(id, {
+      value: instanceOrDescriptor,
+      uid,
+      config: options?.config,
+    });
+    this._emitterFor(id).fire({ oldUid: prev?.uid, newUid: uid });
+    return prev?.value as T | SyncDescriptor<T> | undefined;
+  }
+
+  materialize<T>(id: ServiceIdentifier<T>, instance: T): void {
+    const prev = this._entries.get(id);
+    if (prev === undefined || !(prev.value instanceof SyncDescriptor)) {
+      return;
+    }
+    this._entries.set(id, {
+      value: instance,
+      uid: prev.uid,
+      config: prev.config,
+      recipe: prev.value,
+    });
+  }
+
+  unmaterialize<T>(id: ServiceIdentifier<T>): void {
+    const prev = this._entries.get(id);
+    if (prev === undefined || prev.recipe === undefined) {
+      return;
+    }
+    this._entries.set(id, {
+      value: prev.recipe,
+      uid: prev.uid,
+      config: prev.config,
+    });
+  }
+
+  setConfig<T>(id: ServiceIdentifier<T>, config: unknown): void {
+    const prev = this._entries.get(id);
+    if (prev === undefined) {
+      return;
+    }
+    this._entries.set(id, { ...prev, config });
+  }
+
+  delete<T>(id: ServiceIdentifier<T>): T | SyncDescriptor<T> | undefined {
+    const prev = this._entries.get(id);
+    if (prev === undefined) {
+      return undefined;
+    }
+    this._entries.delete(id);
+    this._emitterFor(id).fire({ oldUid: prev.uid, newUid: undefined });
+    return prev.value as T | SyncDescriptor<T> | undefined;
+  }
+
+  entry(id: ServiceIdentifier<any>): ServiceCollectionEntry | undefined {
+    return this._entries.get(id);
+  }
+
+  uidOf(id: ServiceIdentifier<any>): number | undefined {
+    return this._entries.get(id)?.uid;
+  }
+
+  configOf(id: ServiceIdentifier<any>): unknown {
+    return this._entries.get(id)?.config;
+  }
+
+  onDidChange<T>(
+    id: ServiceIdentifier<T>,
+    listener: (change: AvailabilityChange) => void,
+  ): IDisposable {
+    return this._emitterFor(id).event(listener);
+  }
+
+  has(id: ServiceIdentifier<any>): boolean {
+    return this._entries.has(id);
+  }
+
+  get<T>(id: ServiceIdentifier<T>): T | SyncDescriptor<T> | undefined {
+    return this._entries.get(id)?.value as T | SyncDescriptor<T> | undefined;
+  }
+
+  forEach(
+    callback: (
+      id: ServiceIdentifier<any>,
+      value: unknown,
+    ) => void,
+  ): void {
+    this._entries.forEach((entry, id) => { callback(id, entry.value); });
+  }
+
+  dispose(): void {
+    for (const emitter of this._emitters.values()) {
+      emitter.dispose();
+    }
+    this._emitters.clear();
+  }
+
+  private _emitterFor<T>(id: ServiceIdentifier<T>): Emitter<AvailabilityChange> {
+    let emitter = this._emitters.get(id);
+    if (emitter === undefined) {
+      emitter = new Emitter<AvailabilityChange>();
+      this._emitters.set(id, emitter);
+    }
+    return emitter;
+  }
+}

packages/agent-core-v2/src/_base/di/test.ts

@@ -0,0 +1,53 @@
+export {
+  createServices,
+  TestInstantiationService,
+} from './testInstantiationService';
+export type {
+  CreateServicesOptions,
+  ServiceGroup,
+  ServiceRegistration,
+} from './testInstantiationService';
+
+import { type ServiceIdentifier } from './instantiation';
+import { createAppScope, createScopedChildHandle, Scope, type ScopeKind, type ScopeSeed } from './scope';
+
+export interface ScopedTestHost {
+  readonly app: Scope;
+  child(kind: ScopeKind, id: string, stubs?: ScopeSeed): Scope;
+  childOf(parent: Scope, kind: ScopeKind, id: string, stubs?: ScopeSeed): Scope;
+  dispose(): void;
+}
+
+export function createScopedTestHost(appStubs: ScopeSeed = []): ScopedTestHost {
+  const app = createAppScope({ seeds: appStubs });
+  return {
+    app,
+    child(kind, id, stubs = []) {
+      if (kind === 'program') {
+        const handle = createScopedChildHandle(app.instantiation, kind, id, { seeds: stubs });
+        return {
+          id: handle.id,
+          kind: handle.kind,
+          accessor: handle.accessor,
+          dispose: () => {
+            void handle.dispose();
+          },
+        } as Scope;
+      }
+      return app.createChild(kind, id, { seeds: stubs });
+    },
+    childOf(parent, kind, id, stubs = []) {
+      return parent.createChild(kind, id, { seeds: stubs });
+    },
+    dispose() {
+      app.dispose();
+    },
+  };
+}
+
+export function stubPair<T>(
+  id: ServiceIdentifier<T>,
+  instance: T,
+): readonly [ServiceIdentifier<T>, T] {
+  return [id, instance];
+}

packages/agent-core-v2/src/_base/di/testInstantiationService.ts

@@ -0,0 +1,348 @@
+import * as sinon from 'sinon';
+
+import { SyncDescriptor, type SyncDescriptor0 } from './descriptors';
+import {
+  type GetLeadingNonServiceArgs,
+  type ServiceIdentifier,
+  type ServicesAccessor,
+} from './instantiation';
+import { InstantiationService, Trace } from './instantiationService';
+import { DisposableStore, dispose, isDisposable, toDisposable, type IDisposable } from './lifecycle';
+import { ServiceCollection } from './serviceCollection';
+
+type AnyConstructor<T = unknown> = new (...args: any[]) => T;
+
+interface IServiceMock<T> {
+  id: ServiceIdentifier<T>;
+  service?: any;
+}
+
+const isSinonSpyLike = (fn: Function): fn is sinon.SinonSpy =>
+  fn && 'callCount' in fn;
+
+export class TestInstantiationService extends InstantiationService implements IDisposable, ServicesAccessor {
+  private readonly _classStubs = new Map<Function, unknown>();
+  private readonly _parentTestService?: TestInstantiationService;
+
+  constructor(
+    private readonly _serviceCollection: ServiceCollection = new ServiceCollection(),
+    strict: boolean = false,
+    parent?: InstantiationService,
+    private readonly _properDispose: boolean = true,
+  ) {
+    super(_serviceCollection, strict, parent);
+    if (parent instanceof TestInstantiationService) {
+      this._parentTestService = parent;
+    }
+  }
+
+  public get<T>(id: ServiceIdentifier<T>): T {
+    return super._getOrCreateServiceInstance(
+      id,
+      Trace.traceCreation(false, TestInstantiationService),
+    );
+  }
+
+  public set<T>(
+    id: ServiceIdentifier<T>,
+    instanceOrDescriptor: T | SyncDescriptor<T>,
+  ): T | SyncDescriptor<T> | undefined {
+    const prev = this._serviceCollection.get(id);
+    this.provide(id, instanceOrDescriptor, { activation: 'ondemand' });
+    return prev;
+  }
+
+  public mock<T>(id: ServiceIdentifier<T>): T | sinon.SinonMock {
+    return this._create({ id }, { mock: true });
+  }
+
+  public stubInstance<T>(ctor: AnyConstructor<T>, instance: Partial<T>): void {
+    this._classStubs.set(ctor, instance);
+  }
+
+  protected _getClassStub(ctor: Function): unknown {
+    return this._classStubs.get(ctor) ?? this._parentTestService?._getClassStub(ctor);
+  }
+
+  public override createInstance<T>(descriptor: SyncDescriptor0<T>): T;
+  public override createInstance<
+    Ctor extends AnyConstructor,
+    R extends InstanceType<Ctor>,
+  >(
+    ctor: Ctor,
+    ...args: GetLeadingNonServiceArgs<ConstructorParameters<Ctor>>
+  ): R;
+  public override createInstance(
+    ctorOrDescriptor: any,
+    ...rest: unknown[]
+  ): unknown {
+    const stub =
+      ctorOrDescriptor instanceof SyncDescriptor
+        ? this._getClassStub(ctorOrDescriptor.ctor)
+        : this._getClassStub(ctorOrDescriptor);
+
+    if (stub !== undefined) {
+      return stub;
+    }
+
+    if (ctorOrDescriptor instanceof SyncDescriptor) {
+      return super.createInstance(ctorOrDescriptor, ...rest);
+    }
+    return super.createInstance(ctorOrDescriptor, ...rest);
+  }
+
+  public stub<T>(
+    id: ServiceIdentifier<T>,
+    instanceOrDescriptor: Partial<NoInfer<T>> | SyncDescriptor<T>,
+  ): T | SyncDescriptor<T>;
+  public stub<T>(id: ServiceIdentifier<T>, ctor: AnyConstructor<T>): T;
+  public stub<T, V>(
+    id: ServiceIdentifier<T>,
+    obj: Partial<NoInfer<T>> | Function,
+    property: string,
+    value: V,
+  ): V extends Function ? sinon.SinonSpy : sinon.SinonStub;
+  public stub<T, V>(
+    id: ServiceIdentifier<T>,
+    property: string,
+    value: V,
+  ): V extends Function ? sinon.SinonSpy : sinon.SinonStub;
+  public stub<T>(
+    id: ServiceIdentifier<T>,
+    arg2: any,
+    arg3?: string,
+    arg4?: any,
+  ): T | SyncDescriptor<T> | sinon.SinonStub | sinon.SinonSpy {
+    if (arg2 instanceof SyncDescriptor && typeof arg3 !== 'string') {
+      this._serviceCollection.set(id, arg2);
+      return arg2;
+    }
+
+    if (typeof arg2 !== 'string' && typeof arg3 !== 'string') {
+      const service = this._create(arg2, { stub: true }) as T;
+      this._serviceCollection.set(id, service);
+      return service;
+    }
+
+    const service = typeof arg2 !== 'string' ? arg2 : undefined;
+    const property = typeof arg2 === 'string' ? arg2 : arg3;
+    const value = typeof arg2 === 'string' ? arg3 : arg4;
+
+    if (typeof property !== 'string') {
+      throw new TypeError('stub requires a method/property name');
+    }
+
+    const serviceMock: IServiceMock<T> = { id, service };
+    const stubObject = this._create(serviceMock, { stub: true }, Boolean(service && !property)) as Record<string, unknown>;
+    const replacement = this._createReplacement(value);
+
+    const current = stubObject[property] as { restore?: () => void } | undefined;
+    if (current && typeof current.restore === 'function') {
+      current.restore();
+    }
+    stubObject[property] = replacement;
+    return replacement;
+  }
+
+  public stubPromise<T>(
+    id?: ServiceIdentifier<T>,
+    fnProperty?: string,
+    value?: any,
+  ): T | sinon.SinonStub;
+  public stubPromise<T, V>(
+    id?: ServiceIdentifier<T>,
+    ctor?: any,
+    fnProperty?: string,
+    value?: V,
+  ): V extends Function ? sinon.SinonSpy : sinon.SinonStub;
+  public stubPromise<T, V>(
+    id?: ServiceIdentifier<T>,
+    obj?: any,
+    fnProperty?: string,
+    value?: V,
+  ): V extends Function ? sinon.SinonSpy : sinon.SinonStub;
+  public stubPromise(
+    arg1?: any,
+    arg2?: any,
+    arg3?: any,
+    arg4?: any,
+  ): unknown {
+    arg3 = typeof arg2 === 'string' ? Promise.resolve(arg3) : arg3;
+    arg4 = typeof arg2 !== 'string' && typeof arg3 === 'string' ? Promise.resolve(arg4) : arg4;
+    return this.stub(arg1, arg2, arg3, arg4);
+  }
+
+  public spy<T>(id: ServiceIdentifier<T>, property: string): sinon.SinonSpy {
+    const spy = sinon.spy();
+    this.stub(id, property, spy);
+    return spy;
+  }
+
+  private _create<T>(serviceMock: IServiceMock<T>, options: SinonOptions, reset?: boolean): T;
+  private _create<T>(ctor: any, options: SinonOptions): T | sinon.SinonMock;
+  private _create(arg1: any, options: SinonOptions, reset: boolean = false): any {
+    if (this._isServiceMock(arg1)) {
+      const service = this._getOrCreateService(arg1, options, reset);
+      if (options.mock) {
+        return sinon.mock(service);
+      }
+      this._serviceCollection.set(arg1.id, service);
+      return service;
+    }
+    return options.mock ? sinon.mock(arg1) : this._createStub(arg1);
+  }
+
+  private _getOrCreateService<T>(
+    serviceMock: IServiceMock<T>,
+    opts: SinonOptions,
+    reset?: boolean,
+  ): T {
+    const service = this._serviceCollection.get(serviceMock.id);
+    if (!reset && service && !(service instanceof SyncDescriptor)) {
+      if (opts.stub && this._hasSinonOption(service, 'stub')) {
+        return service as T;
+      }
+      if (opts.mock && this._hasSinonOption(service, 'mock')) {
+        return service as T;
+      }
+      return service as T;
+    }
+    return this._createService(serviceMock, opts);
+  }
+
+  private _createService<T>(serviceMock: IServiceMock<T>, opts: SinonOptions): T {
+    const existing = this._serviceCollection.get(serviceMock.id);
+    const source =
+      serviceMock.service
+      ?? (existing instanceof SyncDescriptor ? existing.ctor : undefined);
+    const service = this._createStub(source);
+    service.sinonOptions = opts;
+    return service as T;
+  }
+
+  private _createStub(arg: any): any {
+    if (arg instanceof SyncDescriptor) {
+      return sinon.createStubInstance(arg.ctor);
+    }
+    if (typeof arg === 'function') {
+      return sinon.createStubInstance(arg);
+    }
+    if (arg && typeof arg === 'object') {
+      return arg;
+    }
+    return Object.create(null);
+  }
+
+  private _createReplacement(value: any): sinon.SinonStub | sinon.SinonSpy {
+    if (typeof value === 'function') {
+      return isSinonSpyLike(value) ? value : sinon.spy(value);
+    }
+    return value ? sinon.stub().returns(value) : sinon.stub();
+  }
+
+  private _hasSinonOption(service: any, key: keyof SinonOptions): boolean {
+    return Boolean(service?.sinonOptions?.[key]);
+  }
+
+  private _isServiceMock(arg: any): arg is IServiceMock<unknown> {
+    return typeof arg === 'object' && arg !== null && 'id' in arg;
+  }
+
+  public override createChild(services: ServiceCollection): TestInstantiationService {
+    return super.createChild(services) as TestInstantiationService;
+  }
+
+  protected override _createChildService(services: ServiceCollection): InstantiationService {
+    return new TestInstantiationService(services, false, this);
+  }
+
+  public override dispose(): void {
+    sinon.restore();
+    if (this._properDispose) {
+      super.dispose();
+    }
+  }
+
+  public override disposeAsync(): Promise<void> {
+    sinon.restore();
+    if (this._properDispose) {
+      return super.disposeAsync();
+    }
+    return Promise.resolve();
+  }
+}
+
+interface SinonOptions {
+  mock?: boolean;
+  stub?: boolean;
+}
+
+export interface ServiceRegistration {
+  define<T>(id: ServiceIdentifier<T>, ctor: new (...args: any[]) => T): void;
+  defineInstance<T>(id: ServiceIdentifier<T>, instance: T): void;
+  definePartialInstance<T>(id: ServiceIdentifier<T>, instance: Partial<T>): void;
+}
+
+export type ServiceGroup = (reg: ServiceRegistration) => void;
+
+export interface CreateServicesOptions {
+  readonly base?: readonly ServiceGroup[];
+  readonly additionalServices?: (reg: ServiceRegistration) => void;
+  readonly strict?: boolean;
+}
+
+export function createServices(
+  disposables: DisposableStore,
+  options: CreateServicesOptions = {},
+): TestInstantiationService {
+  const serviceCollection = new ServiceCollection();
+  const instanceIds = new Set<ServiceIdentifier<any>>();
+
+  const register = <T>(
+    id: ServiceIdentifier<T>,
+    value: T | Partial<T> | SyncDescriptor<T>,
+    isInstance: boolean,
+    overwrite: boolean,
+  ): void => {
+    if (overwrite || !serviceCollection.has(id)) {
+      serviceCollection.set(id, value as T | SyncDescriptor<T>);
+    }
+    if (isInstance) {
+      instanceIds.add(id);
+    }
+  };
+
+  const baseReg: ServiceRegistration = {
+    define: (id, ctor) => register(id, new SyncDescriptor(ctor), false, false),
+    defineInstance: (id, instance) => register(id, instance, true, false),
+    definePartialInstance: (id, instance) => register(id, instance, true, false),
+  };
+
+  for (const group of options.base ?? []) {
+    group(baseReg);
+  }
+
+  if (options.additionalServices) {
+    const overrideReg: ServiceRegistration = {
+      define: (id, ctor) => register(id, new SyncDescriptor(ctor), false, true),
+      defineInstance: (id, instance) => register(id, instance, true, true),
+      definePartialInstance: (id, instance) => register(id, instance, true, true),
+    };
+    options.additionalServices(overrideReg);
+  }
+
+  const instantiationService = disposables.add(
+    new TestInstantiationService(serviceCollection, options.strict ?? false),
+  );
+  disposables.add(toDisposable(() => {
+    const serviceDisposables: IDisposable[] = [];
+    for (const id of instanceIds) {
+      const instance = serviceCollection.get(id);
+      if (isDisposable(instance)) {
+        serviceDisposables.push(instance);
+      }
+    }
+    dispose(serviceDisposables);
+  }));
+  return instantiationService;
+}

packages/agent-core-v2/src/_base/di/util/linkedList.ts

@@ -0,0 +1,84 @@
+class Node<E> {
+  static readonly Undefined = new Node<unknown>(undefined);
+
+  element: E;
+  next: Node<E> | typeof Node.Undefined;
+  prev: Node<E> | typeof Node.Undefined;
+
+  constructor(element: E) {
+    this.element = element;
+    this.next = Node.Undefined;
+    this.prev = Node.Undefined;
+  }
+}
+
+export class LinkedList<E> {
+  private _first: Node<E> | typeof Node.Undefined = Node.Undefined;
+  private _last: Node<E> | typeof Node.Undefined = Node.Undefined;
+  private _size: number = 0;
+
+  get size(): number {
+    return this._size;
+  }
+
+  isEmpty(): boolean {
+    return this._first === Node.Undefined;
+  }
+
+  push(element: E): () => void {
+    const newNode = new Node(element);
+    if (this._first === Node.Undefined) {
+      this._first = newNode;
+      this._last = newNode;
+    } else {
+      const oldLast = this._last as Node<E>;
+      this._last = newNode;
+      newNode.prev = oldLast;
+      oldLast.next = newNode;
+    }
+    this._size += 1;
+
+    let didRemove = false;
+    return () => {
+      if (!didRemove) {
+        didRemove = true;
+        this._remove(newNode);
+      }
+    };
+  }
+
+  shift(): E | undefined {
+    if (this._first === Node.Undefined) {
+      return undefined;
+    }
+    const node = this._first as Node<E>;
+    this._remove(node);
+    return node.element;
+  }
+
+  private _remove(node: Node<E>): void {
+    if (node.prev !== Node.Undefined && node.next !== Node.Undefined) {
+      const anchor = node.prev as Node<E>;
+      anchor.next = node.next;
+      (node.next as Node<E>).prev = anchor;
+    } else if (node.prev === Node.Undefined && node.next === Node.Undefined) {
+      this._first = Node.Undefined;
+      this._last = Node.Undefined;
+    } else if (node.next === Node.Undefined) {
+      this._last = (this._last as Node<E>).prev!;
+      (this._last as Node<E>).next = Node.Undefined;
+    } else if (node.prev === Node.Undefined) {
+      this._first = (this._first as Node<E>).next!;
+      (this._first as Node<E>).prev = Node.Undefined;
+    }
+    this._size -= 1;
+  }
+
+  *[Symbol.iterator](): Iterator<E> {
+    let node = this._first;
+    while (node !== Node.Undefined) {
+      yield (node as Node<E>).element;
+      node = (node as Node<E>).next;
+    }
+  }
+}

packages/agent-core-v2/src/_base/errors/codes.ts

@@ -0,0 +1,70 @@
+export interface ErrorInfo {
+  readonly title: string;
+  readonly retryable: boolean;
+  readonly public: boolean;
+  readonly action?: string;
+}
+
+export interface ErrorDomain {
+  readonly codes: { readonly [name: string]: string };
+  readonly retryable?: ReadonlyArray<string>;
+  readonly info?: { readonly [code: string]: ErrorInfo };
+}
+
+const registeredCodes = new Map<string, object>();
+const retryableCodes = new Set<string>();
+const infoOverrides: { [code: string]: ErrorInfo } = {};
+
+export function registerErrorDomain(domain: ErrorDomain): void {
+  for (const code of Object.values(domain.codes)) {
+    const owner = registeredCodes.get(code);
+    if (owner !== undefined && owner !== domain.codes) {
+      throw new Error(`error code '${code}' is registered by two different domains`);
+    }
+    registeredCodes.set(code, domain.codes);
+  }
+  for (const code of domain.retryable ?? []) {
+    retryableCodes.add(code);
+  }
+  for (const [code, info] of Object.entries(domain.info ?? {})) {
+    infoOverrides[code] = info;
+  }
+}
+
+export function isErrorCode(code: unknown): code is string {
+  return typeof code === 'string' && registeredCodes.has(code);
+}
+
+export function errorInfo(code: string): ErrorInfo {
+  const override = infoOverrides[code];
+  if (override !== undefined) return override;
+  return {
+    title: code,
+    retryable: retryableCodes.has(code),
+    public: true,
+  };
+}
+
+export const CoreErrors = {
+  codes: {
+    INTERNAL: 'internal',
+    NOT_IMPLEMENTED: 'not_implemented',
+    VALIDATION_FAILED: 'validation.failed',
+  },
+  info: {
+    internal: {
+      title: 'Internal error',
+      retryable: false,
+      public: true,
+      action: 'Inspect logs or report the issue with diagnostics.',
+    },
+    not_implemented: {
+      title: 'Not implemented',
+      retryable: false,
+      public: true,
+      action: 'This feature is not implemented yet.',
+    },
+  },
+} as const satisfies ErrorDomain;
+
+registerErrorDomain(CoreErrors);

packages/agent-core-v2/src/_base/errors/errorMessage.ts

@@ -0,0 +1,23 @@
+import { isCodedError } from './serialize';
+
+export function toErrorMessage(error: unknown, verbose = false): string {
+  if (isCodedError(error)) {
+    const base = `[${error.code}] ${error.message}`;
+    return verbose && error.details ? `${base} ${JSON.stringify(error.details)}` : base;
+  }
+  if (error instanceof Error) {
+    const base = error.message || error.name;
+    if (verbose && error.cause !== undefined) {
+      return `${base} (caused by: ${toErrorMessage(error.cause)})`;
+    }
+    return base;
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}

packages/agent-core-v2/src/_base/errors/errors.ts

@@ -0,0 +1,70 @@
+import { CoreErrors } from './codes';
+import type { ErrorCode } from '#/errors';
+
+export class ExpectedError extends Error {
+  readonly isExpected = true;
+}
+
+export class ErrorNoTelemetry extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = 'CodeExpectedError';
+  }
+
+  static fromError(error: Error): ErrorNoTelemetry {
+    const wrapped = new ErrorNoTelemetry(error.message);
+    wrapped.stack = error.stack;
+    return wrapped;
+  }
+
+  static isErrorNoTelemetry(error: unknown): error is ErrorNoTelemetry {
+    return error instanceof Error && error.name === 'CodeExpectedError';
+  }
+}
+
+export class BugIndicatingError extends Error {
+  constructor(message?: string) {
+    super(message ?? 'An unexpected bug occurred.');
+    this.name = 'BugIndicatingError';
+  }
+}
+
+export interface Error2Options {
+  readonly details?: Readonly<Record<string, unknown>>;
+  readonly cause?: unknown;
+  readonly name?: string;
+}
+
+export class Error2 extends Error {
+  readonly code: ErrorCode;
+  readonly details?: Readonly<Record<string, unknown>>;
+
+  constructor(code: ErrorCode, message: string, options?: Error2Options) {
+    super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+    this.name = options?.name ?? 'Error2';
+    this.code = code;
+    this.details = options?.details;
+  }
+}
+
+export function isError2(error: unknown): error is Error2 {
+  return error instanceof Error2;
+}
+
+export function unwrapErrorCause(error: unknown): unknown {
+  let current = error;
+  while (current instanceof Error2 && current.cause !== undefined) {
+    current = current.cause;
+  }
+  return current;
+}
+
+export class NotImplementedError extends Error2 {
+  constructor(feature?: string) {
+    super(
+      CoreErrors.codes.NOT_IMPLEMENTED,
+      feature ? `Not implemented: ${feature}` : 'Not implemented',
+    );
+    this.name = 'NotImplementedError';
+  }
+}

packages/agent-core-v2/src/_base/errors/serialize.ts

@@ -0,0 +1,97 @@
+import { CoreErrors, errorInfo, isErrorCode } from './codes';
+import type { ErrorCode } from '#/errors';
+import { Error2 } from './errors';
+
+export interface ErrorPayload {
+  readonly code: ErrorCode;
+  readonly message: string;
+  readonly name?: string;
+  readonly details?: Readonly<Record<string, unknown>>;
+  readonly retryable: boolean;
+  readonly cause?: ErrorPayload;
+}
+
+export type KimiErrorPayload = ErrorPayload;
+
+export interface CodedErrorShape {
+  readonly code: ErrorCode;
+  readonly message: string;
+  readonly name?: string;
+  readonly details?: Readonly<Record<string, unknown>>;
+}
+
+const MAX_CAUSE_DEPTH = 8;
+
+export function isCodedError(error: unknown): error is CodedErrorShape {
+  if (error === null || typeof error !== 'object') {
+    return false;
+  }
+  const code = (error as { readonly code?: unknown }).code;
+  return isErrorCode(code);
+}
+
+export function makeErrorPayload(
+  code: ErrorCode,
+  message: string,
+  options?: {
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly name?: string;
+  },
+): ErrorPayload {
+  return {
+    code,
+    message,
+    name: options?.name,
+    details: options?.details,
+    retryable: errorInfo(code).retryable,
+  };
+}
+
+export function toErrorPayload(error: unknown): ErrorPayload {
+  return toErrorPayloadAtDepth(error, 0);
+}
+
+function toErrorPayloadAtDepth(error: unknown, depth: number): ErrorPayload {
+  const payload = toShallowErrorPayload(error);
+  if (depth >= MAX_CAUSE_DEPTH) {
+    return payload;
+  }
+  const cause = readErrorCause(error);
+  if (cause === undefined) {
+    return payload;
+  }
+  return { ...payload, cause: toErrorPayloadAtDepth(cause, depth + 1) };
+}
+
+function toShallowErrorPayload(error: unknown): ErrorPayload {
+  if (isCodedError(error)) {
+    return {
+      code: error.code,
+      message: error.message,
+      name: error.name,
+      details: error.details,
+      retryable: errorInfo(error.code).retryable,
+    };
+  }
+  if (error instanceof Error) {
+    return makeErrorPayload(CoreErrors.codes.INTERNAL, error.message, { name: error.name });
+  }
+  return makeErrorPayload(CoreErrors.codes.INTERNAL, String(error));
+}
+
+function readErrorCause(error: unknown): unknown {
+  if (error === null || typeof error !== 'object') {
+    return undefined;
+  }
+  return (error as { readonly cause?: unknown }).cause;
+}
+
+export const toKimiErrorPayload = toErrorPayload;
+
+export function fromErrorPayload(payload: ErrorPayload): Error2 {
+  return new Error2(payload.code, payload.message, {
+    name: payload.name,
+    details: payload.details,
+    cause: payload.cause === undefined ? undefined : fromErrorPayload(payload.cause),
+  });
+}

packages/agent-core-v2/src/_base/errors/unexpectedError.ts

@@ -0,0 +1,31 @@
+export type UnexpectedErrorHandler = (err: unknown) => void;
+
+const defaultHandler: UnexpectedErrorHandler = (err) => {
+  console.error('[unexpected]', err);
+};
+
+let currentHandler: UnexpectedErrorHandler = defaultHandler;
+
+export function setUnexpectedErrorHandler(handler: UnexpectedErrorHandler): void {
+  currentHandler = handler;
+}
+
+export function resetUnexpectedErrorHandler(): void {
+  currentHandler = defaultHandler;
+}
+
+export function onUnexpectedError(err: unknown): void {
+  try {
+    currentHandler(err);
+  } catch (handlerErr) {
+    console.error('[unexpected] handler threw', handlerErr, 'while reporting', err);
+  }
+}
+
+export function safelyCallListener(listener: () => void): void {
+  try {
+    listener();
+  } catch (err) {
+    onUnexpectedError(err);
+  }
+}

packages/agent-core-v2/src/_base/execEnv/bufferedReadable.ts

@@ -0,0 +1,52 @@
+import { Readable } from 'node:stream';
+
+export class BufferedReadable extends Readable {
+  private readonly _source: Readable;
+  private _ended: boolean = false;
+
+  constructor(source: Readable) {
+    super({ highWaterMark: 128 * 1024 });
+    this._source = source;
+    this._source.on('data', this._onData);
+    this._source.on('end', this._onEnd);
+    this._source.on('close', this._onClose);
+    this._source.on('error', this._onError);
+  }
+
+  override _read(): void {
+    if (!this._ended && !this.destroyed) {
+      this._source.resume();
+    }
+  }
+
+  override _destroy(error: Error | null, callback: (error?: Error | null) => void): void {
+    this._source.off('data', this._onData);
+    this._source.off('end', this._onEnd);
+    this._source.off('close', this._onClose);
+    this._source.off('error', this._onError);
+    this._source.destroy();
+    callback(error);
+  }
+
+  private readonly _onData = (chunk: string | Uint8Array): void => {
+    if (!this.push(chunk)) {
+      this._source.pause();
+    }
+  };
+
+  private readonly _onEnd = (): void => {
+    this._ended = true;
+    this.push(null);
+  };
+
+  private readonly _onClose = (): void => {
+    if (!this._ended) {
+      this._ended = true;
+      this.push(null);
+    }
+  };
+
+  private readonly _onError = (error: Error): void => {
+    this.destroy(error);
+  };
+}

packages/agent-core-v2/src/_base/execEnv/decodeText.ts

@@ -0,0 +1,185 @@
+export type TextDecodeErrors = 'strict' | 'replace' | 'ignore';
+
+export async function* readUtf8Lines(
+  source: AsyncIterable<Uint8Array>,
+  errors: TextDecodeErrors = 'strict',
+): AsyncGenerator<string> {
+  let pending: Buffer[] = [];
+  let offset = 0;
+  let pendingOffset = 0;
+  for await (const bytes of source) {
+    const chunk = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let start = 0;
+    for (let i = 0; i < chunk.length; i++) {
+      if (chunk[i] !== 0x0a) continue;
+      const piece = chunk.subarray(start, i + 1);
+      const lineOffset = pending.length === 0 ? offset + start : pendingOffset;
+      const line = pending.length === 0 ? piece : Buffer.concat([...pending, piece]);
+      yield decodeTextWithErrors(line, 'utf-8', errors, lineOffset !== 0);
+      pending = [];
+      start = i + 1;
+    }
+    if (start < chunk.length) {
+      if (pending.length === 0) pendingOffset = offset + start;
+      pending.push(Buffer.from(chunk.subarray(start)));
+    }
+    offset += chunk.length;
+  }
+  if (pending.length > 0) yield decodeTextWithErrors(Buffer.concat(pending), 'utf-8', errors, pendingOffset !== 0);
+}
+
+function isUtf8Continuation(byte: number): boolean {
+  return byte >= 0x80 && byte <= 0xbf;
+}
+
+function decodeUtf8Ignore(data: Buffer): string {
+  let output = '';
+  let i = 0;
+
+  while (i < data.length) {
+    const b0 = data[i];
+    if (b0 === undefined) break;
+
+    if (b0 <= 0x7f) {
+      output += String.fromCodePoint(b0);
+      i += 1;
+      continue;
+    }
+
+    if (b0 >= 0xc2 && b0 <= 0xdf) {
+      const b1 = data[i + 1];
+      if (b1 !== undefined && isUtf8Continuation(b1)) {
+        output += String.fromCodePoint(((b0 & 0x1f) << 6) | (b1 & 0x3f));
+        i += 2;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (b0 >= 0xe0 && b0 <= 0xef) {
+      const b1 = data[i + 1];
+      const b2 = data[i + 2];
+      const validSecond =
+        b1 !== undefined &&
+        ((b0 === 0xe0 && b1 >= 0xa0 && b1 <= 0xbf) ||
+          (b0 >= 0xe1 && b0 <= 0xec && isUtf8Continuation(b1)) ||
+          (b0 === 0xed && b1 >= 0x80 && b1 <= 0x9f) ||
+          (b0 >= 0xee && b0 <= 0xef && isUtf8Continuation(b1)));
+
+      if (validSecond && b2 !== undefined && isUtf8Continuation(b2)) {
+        output += String.fromCodePoint(((b0 & 0x0f) << 12) | ((b1 & 0x3f) << 6) | (b2 & 0x3f));
+        i += 3;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (b0 >= 0xf0 && b0 <= 0xf4) {
+      const b1 = data[i + 1];
+      const b2 = data[i + 2];
+      const b3 = data[i + 3];
+      const validSecond =
+        b1 !== undefined &&
+        ((b0 === 0xf0 && b1 >= 0x90 && b1 <= 0xbf) ||
+          (b0 >= 0xf1 && b0 <= 0xf3 && isUtf8Continuation(b1)) ||
+          (b0 === 0xf4 && b1 >= 0x80 && b1 <= 0x8f));
+
+      if (
+        validSecond &&
+        b2 !== undefined &&
+        b3 !== undefined &&
+        isUtf8Continuation(b2) &&
+        isUtf8Continuation(b3)
+      ) {
+        output += String.fromCodePoint(
+          ((b0 & 0x07) << 18) | ((b1 & 0x3f) << 12) | ((b2 & 0x3f) << 6) | (b3 & 0x3f),
+        );
+        i += 4;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+
+    i += 1;
+  }
+
+  return output;
+}
+
+function decodeUtf16LeIgnore(data: Buffer): string {
+  let output = '';
+  let i = 0;
+
+  while (i + 1 < data.length) {
+    const first = data[i];
+    const second = data[i + 1];
+    if (first === undefined || second === undefined) break;
+
+    const codeUnit = first | (second << 8);
+
+    if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+      const lowFirst = data[i + 2];
+      const lowSecond = data[i + 3];
+      if (lowFirst !== undefined && lowSecond !== undefined) {
+        const low = lowFirst | (lowSecond << 8);
+        if (low >= 0xdc00 && low <= 0xdfff) {
+          const codePoint = 0x10000 + ((codeUnit - 0xd800) << 10) + (low - 0xdc00);
+          output += String.fromCodePoint(codePoint);
+          i += 4;
+          continue;
+        }
+      }
+      i += 2;
+      continue;
+    }
+
+    if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+      i += 2;
+      continue;
+    }
+
+    output += String.fromCodePoint(codeUnit);
+    i += 2;
+  }
+
+  return output;
+}
+
+export function decodeTextWithErrors(
+  data: Buffer,
+  encoding: BufferEncoding,
+  errors: TextDecodeErrors = 'strict',
+  ignoreBOM: boolean = false,
+): string {
+  let webLabel: string | undefined;
+  switch (encoding) {
+    case 'utf-8':
+    case 'utf8':
+      webLabel = 'utf-8';
+      break;
+    case 'utf16le':
+    case 'ucs2':
+    case 'ucs-2':
+      webLabel = 'utf-16le';
+      break;
+    default:
+      webLabel = undefined;
+  }
+
+  if (webLabel === undefined) {
+    return data.toString(encoding);
+  }
+
+  if (errors === 'strict') {
+    return new TextDecoder(webLabel, { fatal: true, ignoreBOM }).decode(data);
+  }
+
+  if (errors === 'ignore') {
+    return webLabel === 'utf-8' ? decodeUtf8Ignore(data) : decodeUtf16LeIgnore(data);
+  }
+
+  return new TextDecoder(webLabel, { fatal: false, ignoreBOM }).decode(data);
+}

packages/agent-core-v2/src/_base/execEnv/environmentProbe.ts

@@ -0,0 +1,322 @@
+import { execFile as nodeExecFile } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import * as nodeOs from 'node:os';
+import * as nodePath from 'node:path';
+
+export type OsKind = string;
+export type ShellName = 'bash' | 'sh';
+export type PathClass = 'posix' | 'win32';
+
+export class ProbeShellNotFoundError extends Error {
+  readonly checked: readonly string[];
+
+  constructor(message: string, checked: readonly string[]) {
+    super(message);
+    this.name = 'ProbeShellNotFoundError';
+    this.checked = checked;
+  }
+}
+
+export interface HostEnvironmentInfo {
+  readonly osKind: OsKind;
+  readonly osArch: string;
+  readonly osVersion: string;
+  readonly shellName: ShellName;
+  readonly shellPath: string;
+  readonly pathClass: PathClass;
+  readonly homeDir: string;
+}
+
+export interface HostEnvironmentProbeDeps {
+  readonly platform: string;
+  readonly arch: string;
+  readonly release: string;
+  readonly homeDir: string;
+  readonly env: Record<string, string | undefined>;
+  readonly isFile: (path: string) => Promise<boolean>;
+  readonly execFileText: (
+    file: string,
+    args: readonly string[],
+    timeoutMs: number,
+  ) => Promise<string | undefined>;
+}
+
+const GIT_EXEC_PATH_TIMEOUT_MS = 5_000;
+
+const MINGW_PREFIX_SET: ReadonlySet<string> = new Set([
+  'mingw32',
+  'mingw64',
+  'ucrt64',
+  'clang64',
+  'clangarm64',
+]);
+
+function resolveOsKind(platform: string): OsKind {
+  switch (platform) {
+    case 'darwin':
+      return 'macOS';
+    case 'linux':
+      return 'Linux';
+    case 'win32':
+      return 'Windows';
+    default:
+      return platform;
+  }
+}
+
+export async function probeHostEnvironment(
+  deps: HostEnvironmentProbeDeps,
+): Promise<HostEnvironmentInfo> {
+  const osKind = resolveOsKind(deps.platform);
+  const osArch = deps.arch;
+  const osVersion = deps.release;
+  const pathClass: PathClass = deps.platform === 'win32' ? 'win32' : 'posix';
+
+  if (deps.platform === 'win32') {
+    const shellPath = await locateWindowsGitBash(deps);
+    return {
+      osKind,
+      osArch,
+      osVersion,
+      shellName: 'bash',
+      shellPath,
+      pathClass,
+      homeDir: deps.homeDir,
+    };
+  }
+
+  const candidates: readonly string[] = ['/bin/bash', '/usr/bin/bash', '/usr/local/bin/bash'];
+  let found: string | undefined;
+  for (const p of candidates) {
+    if (await deps.isFile(p)) {
+      found = p;
+      break;
+    }
+  }
+  if (found !== undefined) {
+    return {
+      osKind,
+      osArch,
+      osVersion,
+      shellName: 'bash',
+      shellPath: found,
+      pathClass,
+      homeDir: deps.homeDir,
+    };
+  }
+  return {
+    osKind,
+    osArch,
+    osVersion,
+    shellName: 'sh',
+    shellPath: '/bin/sh',
+    pathClass,
+    homeDir: deps.homeDir,
+  };
+}
+
+async function locateWindowsGitBash(deps: HostEnvironmentProbeDeps): Promise<string> {
+  const checked: string[] = [];
+
+  const override = deps.env['KIMI_SHELL_PATH']?.trim();
+  if (override !== undefined && override.length > 0) {
+    checked.push(override);
+    if (await deps.isFile(override)) {
+      return override;
+    }
+  }
+
+  const gitExecutables = await findExecutablesOnPath(
+    'git.exe',
+    deps.env['PATH'],
+    deps.platform,
+    deps.isFile,
+  );
+
+  for (const gitExe of gitExecutables) {
+    const inferred = gitBashCandidatesFromGitExe(gitExe);
+    if (inferred !== undefined) {
+      for (const candidate of inferred) {
+        checked.push(candidate);
+        if (await deps.isFile(candidate)) {
+          return candidate;
+        }
+      }
+    }
+
+    const gitExecPath = await readGitExecPath(deps, gitExe);
+    if (gitExecPath === undefined) {
+      continue;
+    }
+    for (const candidate of gitBashCandidatesFromGitExecPath(gitExecPath)) {
+      checked.push(candidate);
+      if (await deps.isFile(candidate)) {
+        return candidate;
+      }
+    }
+  }
+
+  const candidates: string[] = [
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\usr\\bin\\bash.exe',
+  ];
+  const localAppData = deps.env['LOCALAPPDATA']?.trim();
+  if (localAppData !== undefined && localAppData.length > 0) {
+    candidates.push(`${localAppData}\\Programs\\Git\\bin\\bash.exe`);
+    candidates.push(`${localAppData}\\Programs\\Git\\usr\\bin\\bash.exe`);
+  }
+  for (const candidate of candidates) {
+    checked.push(candidate);
+    if (await deps.isFile(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new ProbeShellNotFoundError(
+    'Git Bash was not found on this Windows host. Install Git for Windows from https://gitforwindows.org/ or set KIMI_SHELL_PATH to a bash.exe.',
+    checked,
+  );
+}
+
+async function readGitExecPath(
+  deps: HostEnvironmentProbeDeps,
+  gitExe: string,
+): Promise<string | undefined> {
+  if (deps.platform === 'win32' && !isAbsoluteWindowsPath(gitExe)) return undefined;
+
+  const stdout = await deps.execFileText(gitExe, ['--exec-path'], GIT_EXEC_PATH_TIMEOUT_MS);
+  if (stdout === undefined) return undefined;
+
+  for (const line of stdout.split(/\r?\n/)) {
+    const execPath = line.trim();
+    if (execPath.length > 0) {
+      return execPath;
+    }
+  }
+  return undefined;
+}
+
+function gitBashCandidatesFromGitExe(gitExe: string): readonly string[] | undefined {
+  const normalizedGitExe = nodePath.win32.normalize(normalizeWindowsPath(gitExe));
+  const gitDir = nodePath.win32.dirname(normalizedGitExe);
+  const gitDirName = nodePath.win32.basename(gitDir).toLowerCase();
+  if (gitDirName !== 'cmd' && gitDirName !== 'bin') {
+    return undefined;
+  }
+  return gitBashCandidatesFromGitRoot(nodePath.win32.dirname(gitDir));
+}
+
+function gitBashCandidatesFromGitExecPath(execPath: string): readonly string[] {
+  const normalized = nodePath.win32.normalize(normalizeWindowsPath(execPath));
+  const parts = normalized.split('\\');
+  for (let i = parts.length - 1; i >= 0; i -= 1) {
+    const segment = parts[i]?.toLowerCase();
+    if (segment !== undefined && MINGW_PREFIX_SET.has(segment)) {
+      const root = parts.slice(0, i).join('\\');
+      if (root.length > 0) {
+        return gitBashCandidatesFromGitRoot(root);
+      }
+    }
+  }
+
+  return gitBashCandidatesFromGitRoot(nodePath.win32.join(normalized, '..', '..'));
+}
+
+function gitBashCandidatesFromGitRoot(root: string): readonly string[] {
+  return [
+    nodePath.win32.normalize(nodePath.win32.join(root, 'bin', 'bash.exe')),
+    nodePath.win32.normalize(nodePath.win32.join(root, 'usr', 'bin', 'bash.exe')),
+  ];
+}
+
+function normalizeWindowsPath(path: string): string {
+  return path.replaceAll('/', '\\');
+}
+
+function isAbsoluteWindowsPath(path: string): boolean {
+  return nodePath.win32.isAbsolute(normalizeWindowsPath(path));
+}
+
+function dedupeWindowsPaths(paths: readonly string[]): readonly string[] {
+  const deduped: string[] = [];
+  const seen = new Set<string>();
+  for (const path of paths) {
+    const key = normalizeWindowsPath(path).toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(path);
+  }
+  return deduped;
+}
+
+let cachedProbe: Promise<HostEnvironmentInfo> | undefined;
+
+export function probeHostEnvironmentFromNode(): Promise<HostEnvironmentInfo> {
+  if (cachedProbe !== undefined) return cachedProbe;
+  const platform = process.platform;
+  const env = process.env as Record<string, string | undefined>;
+  const isFile = async (path: string): Promise<boolean> => {
+    try {
+      await access(path, fsConstants.F_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  cachedProbe = probeHostEnvironment({
+    platform,
+    arch: process.arch,
+    release: nodeOs.release(),
+    homeDir: nodeOs.homedir(),
+    env,
+    isFile,
+    execFileText,
+  });
+  return cachedProbe;
+}
+
+async function findExecutablesOnPath(
+  name: string,
+  pathEnv: string | undefined,
+  platform: string,
+  isFile: (p: string) => Promise<boolean>,
+): Promise<readonly string[]> {
+  if (pathEnv === undefined || pathEnv.length === 0) return [];
+  const listSep = platform === 'win32' ? ';' : ':';
+  const dirSep = platform === 'win32' ? '\\' : '/';
+  const paths: string[] = [];
+  for (const rawDir of pathEnv.split(listSep)) {
+    const dir = rawDir.trim();
+    if (dir.length === 0) continue;
+    if (platform === 'win32' && !isAbsoluteWindowsPath(dir)) continue;
+    const candidate = dir.endsWith(dirSep) ? `${dir}${name}` : `${dir}${dirSep}${name}`;
+    if (await isFile(candidate)) {
+      paths.push(candidate);
+    }
+  }
+  return platform === 'win32' ? dedupeWindowsPaths(paths) : paths;
+}
+
+export async function execFileText(
+  file: string,
+  args: readonly string[],
+  timeoutMs: number,
+): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    nodeExecFile(
+      file,
+      [...args],
+      { encoding: 'utf8', timeout: timeoutMs, windowsHide: true },
+      (error, stdout) => {
+        if (error !== null) {
+          resolve(undefined);
+          return;
+        }
+        resolve(stdout);
+      },
+    );
+  });
+}

packages/agent-core-v2/src/_base/execEnv/globPattern.ts

@@ -0,0 +1,46 @@
+export function globPatternToRegex(pattern: string, caseSensitive: boolean): RegExp {
+  let regex = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === undefined) break;
+    switch (ch) {
+      case '*':
+        regex += '[^/]*';
+        break;
+      case '?':
+        regex += '[^/]';
+        break;
+      case '[': {
+        const end = pattern.indexOf(']', i + 1);
+        if (end === -1) {
+          regex += '\\[';
+        } else {
+          let charClass = pattern.slice(i + 1, end);
+          charClass = charClass.replace(/\\/g, '\\\\');
+          if (charClass.startsWith('!')) {
+            charClass = '^' + charClass.slice(1);
+          } else if (charClass.startsWith('^')) {
+            charClass = '\\' + charClass;
+          }
+          regex += '[' + charClass + ']';
+          i = end;
+        }
+        break;
+      }
+      case '\\': {
+        if (i + 1 < pattern.length) {
+          const next = pattern.charAt(i + 1);
+          regex += next.replaceAll(/[{}()+.\\[\]^$|]/g, '\\$&');
+          i++;
+        } else {
+          regex += '\\\\';
+        }
+        break;
+      }
+      default:
+        regex += ch.replaceAll(/[{}()+.\\[\]^$|]/g, '\\$&');
+    }
+  }
+  regex += '$';
+  return new RegExp(regex, caseSensitive ? '' : 'i');
+}

packages/agent-core-v2/src/_base/execEnv/loginShellPath.ts

@@ -0,0 +1,80 @@
+import { userInfo } from 'node:os';
+
+import { execFileText } from './environmentProbe';
+
+export interface LoginShellPathDeps {
+  readonly platform: string;
+  readonly env: Record<string, string | undefined>;
+  readonly userShell: () => string | undefined;
+  readonly execFileText: (
+    file: string,
+    args: readonly string[],
+    timeoutMs: number,
+  ) => Promise<string | undefined>;
+}
+
+const LOGIN_SHELL_ENV_TIMEOUT_MS = 5_000;
+
+export async function probeLoginShellPath(deps: LoginShellPathDeps): Promise<string | undefined> {
+  if (deps.platform === 'win32') return undefined;
+  const envShell = deps.env['SHELL']?.trim();
+  const shell = envShell === undefined || envShell.length === 0 ? deps.userShell() : envShell;
+  if (shell === undefined || shell.length === 0) return undefined;
+
+  const stdout = await deps.execFileText(shell, ['-l', '-c', '/usr/bin/env'], LOGIN_SHELL_ENV_TIMEOUT_MS);
+  if (stdout === undefined) return undefined;
+
+  let path: string | undefined;
+  for (const line of stdout.split('\n')) {
+    if (line.startsWith('PATH=')) {
+      path = line.slice('PATH='.length).trim();
+    }
+  }
+  if (path === undefined || path.length === 0) return undefined;
+  return path;
+}
+
+export function mergeLoginShellPath(currentPath: string | undefined, loginShellPath: string): string {
+  const current = currentPath ?? '';
+  const seen = new Set(current.split(':').filter((entry) => entry.length > 0));
+  const additions: string[] = [];
+  for (const entry of loginShellPath.split(':')) {
+    if (!entry.startsWith('/') || seen.has(entry)) continue;
+    seen.add(entry);
+    additions.push(entry);
+  }
+  if (additions.length === 0) return current;
+  if (currentPath === undefined) return additions.join(':');
+  return `${current}:${additions.join(':')}`;
+}
+
+export async function applyLoginShellPath(deps: LoginShellPathDeps): Promise<void> {
+  const loginShellPath = await probeLoginShellPath(deps);
+  if (loginShellPath === undefined) return;
+  const currentPath = deps.env['PATH'];
+  const merged = mergeLoginShellPath(currentPath, loginShellPath);
+  if (merged === (currentPath ?? '')) return;
+  deps.env['PATH'] = merged;
+}
+
+function userShellFromNode(): string | undefined {
+  try {
+    const shell = userInfo().shell;
+    return shell === null || shell.length === 0 ? undefined : shell;
+  } catch {
+    return undefined;
+  }
+}
+
+let appliedLoginShellPath: Promise<void> | undefined;
+
+export function applyLoginShellPathFromNode(): Promise<void> {
+  if (appliedLoginShellPath !== undefined) return appliedLoginShellPath;
+  appliedLoginShellPath = applyLoginShellPath({
+    platform: process.platform,
+    env: process.env as Record<string, string | undefined>,
+    userShell: userShellFromNode,
+    execFileText,
+  });
+  return appliedLoginShellPath;
+}

packages/agent-core-v2/src/_base/execEnv/shellPathBridge.ts

@@ -0,0 +1,150 @@
+import { execFileSync as nodeExecFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import * as nodePath from 'node:path';
+
+import type { HostEnvironmentInfo } from './environmentProbe';
+
+export interface ShellPathBridge {
+  toShellPath(nativePath: string): string;
+  fromShellPath(path: string): string;
+}
+
+export type ShellPathBridgeEnv = Pick<HostEnvironmentInfo, 'osKind' | 'shellName' | 'shellPath'>;
+
+export interface ShellPathBridgeDeps {
+  readonly execFileSync: (file: string, args: readonly string[]) => string;
+  readonly isFile: (path: string) => boolean;
+}
+
+const CYGPATH_TIMEOUT_MS = 5_000;
+
+const DRIVE_COLON_RE = /^\/([a-zA-Z]):(?:[\\/]|$)/;
+const CYGDRIVE_RE = /^\/cygdrive\/([a-zA-Z])(?:\/|$)/;
+const DRIVE_RE = /^\/([a-zA-Z])(?:\/|$)/;
+
+const VIRTUAL_FS_PREFIXES: readonly string[] = ['/dev/', '/proc/', '/sys/'];
+
+const WIN32_DRIVE_ABSOLUTE_RE = /^[A-Za-z]:[\\/]/;
+
+function joinDrive(letter: string, rest: string): string {
+  const normalizedRest = rest.replaceAll('\\', '/');
+  return normalizedRest === ''
+    ? `${letter.toUpperCase()}:/`
+    : `${letter.toUpperCase()}:${normalizedRest}`;
+}
+
+export function translateShellDrivePath(path: string): string {
+  const colonMatch = DRIVE_COLON_RE.exec(path);
+  if (colonMatch !== null) {
+    return joinDrive(colonMatch[1]!, path.slice(3));
+  }
+  const cygdriveMatch = CYGDRIVE_RE.exec(path);
+  if (cygdriveMatch !== null) {
+    return joinDrive(cygdriveMatch[1]!, path.slice(`/cygdrive/${cygdriveMatch[1]!}`.length));
+  }
+  const driveMatch = DRIVE_RE.exec(path);
+  if (driveMatch !== null) {
+    return joinDrive(driveMatch[1]!, path.slice(2));
+  }
+  return path;
+}
+
+export function createShellPathBridge(
+  env: ShellPathBridgeEnv,
+  deps: ShellPathBridgeDeps,
+): ShellPathBridge {
+  const enabled = env.osKind === 'Windows' && env.shellName === 'bash';
+
+  let cygpathExe: string | null | undefined;
+  const segmentCache = new Map<string, string>();
+
+  function locateCygpath(): string | null {
+    if (cygpathExe !== undefined) return cygpathExe;
+    const shellDir = nodePath.win32.dirname(env.shellPath);
+    const candidates = [nodePath.win32.join(shellDir, 'cygpath.exe')];
+    if (nodePath.win32.basename(shellDir).toLowerCase() === 'bin') {
+      candidates.push(nodePath.win32.join(shellDir, '..', 'usr', 'bin', 'cygpath.exe'));
+    }
+    cygpathExe = candidates.find((candidate) => deps.isFile(candidate)) ?? null;
+    return cygpathExe;
+  }
+
+  function resolveRootSegment(firstSegment: string): string | null {
+    const cached = segmentCache.get(firstSegment);
+    if (cached !== undefined) return cached;
+
+    const exe = locateCygpath();
+    if (exe === null) return null;
+    let resolved: string;
+    try {
+      const output = deps.execFileSync(exe, ['-w', '-C', 'UTF8', '--', `/${firstSegment}`]);
+      const trimmed = output.replace(/\r?\n$/, '');
+      if (!WIN32_DRIVE_ABSOLUTE_RE.test(trimmed) && !trimmed.startsWith('\\\\')) return null;
+      resolved = trimmed.replace(/[\\/]$/, '');
+    } catch {
+      return null;
+    }
+    segmentCache.set(firstSegment, resolved);
+    return resolved;
+  }
+
+  function fromShellPath(path: string): string {
+    if (!enabled) return path;
+
+    if (path.startsWith('//')) return path;
+
+    if (path.startsWith('/')) {
+      const normalized = nodePath.posix.normalize(path);
+      const lexical = translateShellDrivePath(normalized);
+      if (lexical !== normalized) return lexical;
+      if (normalized === '/') return normalized;
+      if (VIRTUAL_FS_PREFIXES.some((prefix) => normalized.startsWith(prefix))) return normalized;
+      const firstSegment = normalized.slice(1).split('/')[0]!;
+      const prefix = resolveRootSegment(firstSegment);
+      if (prefix === null) return normalized;
+      const remainder = normalized.slice(firstSegment.length + 1);
+      const joined = `${prefix}${remainder}`.replaceAll('\\', '/');
+      return /^[A-Za-z]:$/.test(joined) ? `${joined}/` : joined;
+    }
+
+    return path;
+  }
+
+  function toShellPath(nativePath: string): string {
+    if (!enabled) return nativePath;
+
+    if (nativePath.startsWith('\\\\')) {
+      return nativePath.replaceAll('\\', '/');
+    }
+
+    const driveMatch = /^([A-Za-z]):(?:[\\/]|$)/.exec(nativePath);
+    if (driveMatch !== null) {
+      const drive = driveMatch[1]!.toLowerCase();
+      const rest = nativePath.slice(2).replaceAll('\\', '/');
+      return `/${drive}${rest.startsWith('/') ? rest : `/${rest}`}`;
+    }
+
+    return nativePath.replaceAll('\\', '/');
+  }
+
+  return { toShellPath, fromShellPath };
+}
+
+const bridgeCache = new Map<string, ShellPathBridge>();
+
+export function getShellPathBridge(env: ShellPathBridgeEnv): ShellPathBridge {
+  const key = `${env.osKind} ${env.shellName} ${env.shellPath}`;
+  const cached = bridgeCache.get(key);
+  if (cached !== undefined) return cached;
+  const bridge = createShellPathBridge(env, {
+    execFileSync: (file, args) =>
+      nodeExecFileSync(file, [...args], {
+        encoding: 'utf8',
+        timeout: CYGPATH_TIMEOUT_MS,
+        windowsHide: true,
+      }),
+    isFile: (path) => existsSync(path),
+  });
+  bridgeCache.set(key, bridge);
+  return bridge;
+}

packages/agent-core-v2/src/_base/lifecycle/disposer.ts

@@ -0,0 +1,37 @@
+export type TeardownReason = 'scope-close' | 'cascade' | 'unload';
+
+export type Disposer = (reason: TeardownReason) => void | Promise<void>;
+
+export type EffectResult =
+  | void
+  | Disposer
+  | Promise<Disposer | void>
+  | Iterable<Disposer | void>
+  | AsyncIterable<Disposer | void>;
+
+export type EffectBody = () => EffectResult;
+
+export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === 'function'
+  );
+}
+
+export function isSyncIterable(value: unknown): value is Iterable<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { [Symbol.iterator]?: unknown })[Symbol.iterator] === 'function'
+  );
+}
+
+export function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] ===
+      'function'
+  );
+}

packages/agent-core-v2/src/_base/lifecycle/errors.ts

@@ -0,0 +1,12 @@
+export class LedgerDisposedError extends Error {
+  constructor(
+    readonly ledgerLabel: string,
+    readonly operation: string,
+    readonly ledgerState: 'disposing' | 'disposed',
+  ) {
+    super(
+      `Ledger '${ledgerLabel}' is ${ledgerState}: cannot ${operation} on a ${ledgerState} ledger`,
+    );
+    this.name = 'LedgerDisposedError';
+  }
+}

packages/agent-core-v2/src/_base/lifecycle/index.ts

@@ -0,0 +1,4 @@
+export * from './disposer';
+export * from './errors';
+export * from './ledger';
+export * from './lifecycleMachine';

packages/agent-core-v2/src/_base/lifecycle/keyedResource.ts

@@ -0,0 +1,150 @@
+export interface KeyedResourceGeneration {
+  readonly owner: string;
+  readonly generation: string | number;
+}
+
+export interface KeyedResource {
+  dispose(): void | Promise<void>;
+  abort?(reason?: unknown): void;
+}
+
+export interface KeyedResourceLease<Resource> {
+  readonly resource: Resource;
+  release(): void;
+}
+
+interface ResourceEntry<Resource extends KeyedResource> {
+  promise: Promise<Resource>;
+  resource?: Resource;
+  leases: number;
+  draining: boolean;
+  abortOnDrain: boolean;
+  aborted: boolean;
+  disposed: boolean;
+  drainPromise?: Promise<void>;
+  releaseDrain?: () => void;
+}
+
+export class KeyedResourceLeasePool<Key, Resource extends KeyedResource> {
+  private readonly entries = new Map<Key, ResourceEntry<Resource>>();
+  private withdrawn = false;
+  private withdrawal?: Promise<void>;
+
+  constructor(
+    readonly identity: KeyedResourceGeneration,
+    private readonly create: (key: Key) => Resource | Promise<Resource>,
+  ) {}
+
+  acquire(key: Key): Promise<KeyedResourceLease<Resource>> {
+    if (this.withdrawn) return Promise.reject(this.unavailable());
+    let entry = this.entries.get(key);
+    if (entry === undefined) {
+      entry = this.createEntry(key);
+      this.entries.set(key, entry);
+    }
+    if (entry.draining) return Promise.reject(this.unavailable());
+    entry.leases += 1;
+    return entry.promise.then(
+      (resource) => {
+        let active = true;
+        return {
+          resource,
+          release: () => {
+            if (!active) return;
+            active = false;
+            entry.leases -= 1;
+            if (entry.leases === 0) entry.releaseDrain?.();
+          },
+        };
+      },
+      (error: unknown) => {
+        entry.leases -= 1;
+        if (entry.leases === 0) entry.releaseDrain?.();
+        throw error;
+      },
+    );
+  }
+
+  has(key: Key): boolean {
+    return this.entries.has(key);
+  }
+
+  disposeKey(key: Key, reason?: unknown, abort = false): Promise<void> {
+    const entry = this.entries.get(key);
+    if (entry === undefined) return Promise.resolve();
+    this.entries.delete(key);
+    return this.drain(entry, reason, abort);
+  }
+
+  withdraw(reason?: unknown): Promise<void> {
+    if (this.withdrawal !== undefined) return this.withdrawal;
+    this.withdrawn = true;
+    const entries = [...this.entries.values()];
+    this.entries.clear();
+    this.withdrawal = Promise.all(entries.map((entry) => this.drain(entry, reason, false))).then(
+      () => undefined,
+    );
+    return this.withdrawal;
+  }
+
+  private createEntry(key: Key): ResourceEntry<Resource> {
+    const entry: ResourceEntry<Resource> = {
+      promise: undefined as unknown as Promise<Resource>,
+      leases: 0,
+      draining: false,
+      abortOnDrain: false,
+      aborted: false,
+      disposed: false,
+    };
+    entry.promise = Promise.resolve()
+      .then(() => this.create(key))
+      .then(
+        (resource) => {
+          entry.resource = resource;
+          if (entry.abortOnDrain) this.abort(entry);
+          return resource;
+        },
+        (error: unknown) => {
+          if (this.entries.get(key) === entry) this.entries.delete(key);
+          throw error;
+        },
+      );
+    return entry;
+  }
+
+  private drain(entry: ResourceEntry<Resource>, reason?: unknown, abort = false): Promise<void> {
+    entry.abortOnDrain ||= abort;
+    entry.drainPromise ??= (async () => {
+      entry.draining = true;
+      try {
+        await entry.promise;
+      } catch {
+        return;
+      }
+      if (entry.abortOnDrain) this.abort(entry, reason);
+      if (entry.leases > 0) {
+        await new Promise<void>((resolve) => {
+          entry.releaseDrain = resolve;
+        });
+      }
+      if (entry.disposed) return;
+      entry.disposed = true;
+      await entry.resource!.dispose();
+    })();
+    return entry.drainPromise;
+  }
+
+  private abort(entry: ResourceEntry<Resource>, reason?: unknown): void {
+    if (entry.aborted || entry.resource?.abort === undefined) return;
+    entry.aborted = true;
+    try {
+      entry.resource.abort(reason);
+    } catch {}
+  }
+
+  private unavailable(): Error {
+    return new Error(
+      `resource generation ${this.identity.owner}:${String(this.identity.generation)} is withdrawn`,
+    );
+  }
+}

packages/agent-core-v2/src/_base/lifecycle/ledger.ts

@@ -0,0 +1,317 @@
+import { onUnexpectedError } from '../errors/unexpectedError';
+import {
+  isAsyncIterable,
+  isPromiseLike,
+  isSyncIterable,
+  type Disposer,
+  type EffectBody,
+  type TeardownReason,
+} from './disposer';
+import { LedgerDisposedError } from './errors';
+
+export type LedgerState = 'active' | 'disposing' | 'disposed';
+
+export interface LedgerEntryInfo {
+  readonly label: string;
+  readonly kind: 'disposer' | 'effect' | 'ledger';
+  readonly stack?: string;
+  readonly children?: readonly LedgerEntryInfo[];
+}
+
+export interface LedgerEntry {
+  readonly label: string;
+  readonly disposed: boolean;
+  dispose(reason?: TeardownReason): void | Promise<void>;
+  release(): void;
+}
+
+interface EntryRecord {
+  label: string;
+  kind: 'disposer' | 'effect' | 'ledger';
+  stack?: string;
+  active: boolean;
+  run: Disposer;
+  ledger?: Ledger;
+}
+
+export class Ledger {
+  static captureStacks = false;
+
+  private _state: LedgerState = 'active';
+  private readonly _records: EntryRecord[] = [];
+  private _teardownPromise: Promise<void> | undefined;
+  private _parentEntry: LedgerEntry | undefined;
+
+  constructor(readonly label: string = 'ledger') {}
+
+  get state(): LedgerState {
+    return this._state;
+  }
+
+  get isActive(): boolean {
+    return this._state === 'active';
+  }
+
+  get isDisposed(): boolean {
+    return this._state === 'disposed';
+  }
+
+  get size(): number {
+    return this._records.reduce((count, record) => count + (record.active ? 1 : 0), 0);
+  }
+
+  register(disposer: Disposer, label: string = 'disposer'): LedgerEntry {
+    this._assertActive('register');
+    return this._push({ label, kind: 'disposer', active: true, run: disposer });
+  }
+
+  registerFinalizer(disposer: Disposer, label: string = 'finalizer'): LedgerEntry {
+    this._assertActive('registerFinalizer');
+    return this._push({ label, kind: 'disposer', active: true, run: disposer }, true);
+  }
+
+  effect(body: EffectBody, label: string = 'effect'): LedgerEntry {
+    this._assertActive('effect');
+    const out = body();
+    if (typeof out === 'function') {
+      return this._push({ label, kind: 'effect', active: true, run: out });
+    }
+    if (isPromiseLike(out)) {
+      const promise = Promise.resolve(out);
+      return this._push({
+        label,
+        kind: 'effect',
+        active: true,
+        run: async (reason) => {
+          const disposer = await promise;
+          if (typeof disposer === 'function') await disposer(reason);
+        },
+      });
+    }
+    if (isAsyncIterable(out)) {
+      const promise = driveAsyncEffect(out);
+      return this._push({
+        label,
+        kind: 'effect',
+        active: true,
+        run: async (reason) => {
+          const disposer = await promise;
+          await disposer(reason);
+        },
+      });
+    }
+    if (isSyncIterable(out)) {
+      const run = driveSyncEffect(out);
+      return this._push({ label, kind: 'effect', active: true, run });
+    }
+    return this._push({ label, kind: 'effect', active: true, run: () => {} });
+  }
+
+  createChild(label: string = 'ledger'): Ledger {
+    this._assertActive('createChild');
+    const child = new Ledger(label);
+    child._parentEntry = this._push({
+      label,
+      kind: 'ledger',
+      active: true,
+      run: (reason) => child.teardown(reason),
+      ledger: child,
+    });
+    return child;
+  }
+
+  teardown(reason: TeardownReason = 'scope-close'): void | Promise<void> {
+    if (this._state !== 'active') {
+      return this._teardownPromise;
+    }
+    this._state = 'disposing';
+    this._detachFromParent();
+    const out = drainRecords(this._records, reason);
+    if (isPromiseLike(out)) {
+      this._teardownPromise = Promise.resolve(out).then(() => {
+        this._state = 'disposed';
+      });
+      return this._teardownPromise;
+    }
+    this._state = 'disposed';
+    return undefined;
+  }
+
+  clear(reason: TeardownReason = 'scope-close'): void | Promise<void> {
+    this._assertActive('clear');
+    return drainRecords(this._records, reason);
+  }
+
+  entries(): LedgerEntryInfo[] {
+    const infos: LedgerEntryInfo[] = [];
+    for (const record of this._records) {
+      if (!record.active) continue;
+      infos.push({
+        label: record.label,
+        kind: record.kind,
+        stack: record.stack,
+        children: record.ledger?.entries(),
+      });
+    }
+    return infos;
+  }
+
+  private _push(record: EntryRecord, front = false): LedgerEntry {
+    if (Ledger.captureStacks) {
+      record.stack = new Error('Ledger registration').stack;
+    }
+    if (front) {
+      this._records.unshift(record);
+    } else {
+      this._records.push(record);
+    }
+    return {
+      label: record.label,
+      get disposed() {
+        return !record.active;
+      },
+      dispose: (reason: TeardownReason = 'scope-close') => {
+        if (!record.active) return undefined;
+        record.active = false;
+        this._remove(record);
+        return runGuarded(record, reason);
+      },
+      release: () => {
+        if (!record.active) return;
+        record.active = false;
+        this._remove(record);
+      },
+    };
+  }
+
+  private _remove(record: EntryRecord): void {
+    const index = this._records.indexOf(record);
+    if (index >= 0) {
+      this._records.splice(index, 1);
+    }
+  }
+
+  private _detachFromParent(): void {
+    this._parentEntry?.release();
+    this._parentEntry = undefined;
+  }
+
+  private _assertActive(operation: string): void {
+    if (this._state !== 'active') {
+      throw new LedgerDisposedError(this.label, operation, this._state);
+    }
+  }
+}
+
+function runGuarded(record: EntryRecord, reason: TeardownReason): void | Promise<void> {
+  let out: void | Promise<void>;
+  try {
+    out = record.run(reason);
+  } catch (error) {
+    onUnexpectedError(tagged(error, record.label));
+    return undefined;
+  }
+  if (isPromiseLike(out)) {
+    return Promise.resolve(out).catch((error: unknown) => {
+      onUnexpectedError(tagged(error, record.label));
+    });
+  }
+  return undefined;
+}
+
+function tagged(error: unknown, label: string): unknown {
+  if (error instanceof Error) {
+    error.message = `[ledger:${label}] ${error.message}`;
+    return error;
+  }
+  return new Error(`[ledger:${label}] ${String(error)}`);
+}
+
+function drainRecords(records: EntryRecord[], reason: TeardownReason): void | Promise<void> {
+  let index = records.length;
+  const step = (): void | Promise<void> => {
+    while (index > 0) {
+      index -= 1;
+      const record = records[index]!;
+      if (!record.active) continue;
+      record.active = false;
+      const out = runGuarded(record, reason);
+      if (isPromiseLike(out)) {
+        return Promise.resolve(out).then(step);
+      }
+    }
+    records.length = 0;
+    return undefined;
+  };
+  return step();
+}
+
+function runDisposersReverse(
+  disposers: readonly Disposer[],
+  reason: TeardownReason,
+): void | Promise<void> {
+  let index = disposers.length;
+  const step = (): void | Promise<void> => {
+    while (index > 0) {
+      index -= 1;
+      const disposer = disposers[index]!;
+      let out: void | Promise<void>;
+      try {
+        out = disposer(reason);
+      } catch (error) {
+        onUnexpectedError(tagged(error, 'effect'));
+        continue;
+      }
+      if (isPromiseLike(out)) {
+        return Promise.resolve(out)
+          .catch((error: unknown) => { onUnexpectedError(tagged(error, 'effect')); })
+          .then(step);
+      }
+    }
+    return undefined;
+  };
+  return step();
+}
+
+function collect(step: IteratorResult<Disposer | void>, disposers: Disposer[]): void {
+  if (typeof step.value === 'function') {
+    disposers.push(step.value);
+  }
+}
+
+function driveSyncEffect(iterable: Iterable<Disposer | void>): Disposer {
+  const disposers: Disposer[] = [];
+  const iterator = iterable[Symbol.iterator]();
+  try {
+    let step = iterator.next();
+    while (!step.done) {
+      collect(step, disposers);
+      step = iterator.next();
+    }
+    collect(step, disposers);
+  } catch (error) {
+    const rollback = runDisposersReverse(disposers, 'unload');
+    if (isPromiseLike(rollback)) {
+      Promise.resolve(rollback).catch((error: unknown) => { onUnexpectedError(error); });
+    }
+    throw error;
+  }
+  return (reason) => runDisposersReverse(disposers, reason);
+}
+
+async function driveAsyncEffect(iterable: AsyncIterable<Disposer | void>): Promise<Disposer> {
+  const disposers: Disposer[] = [];
+  const iterator = iterable[Symbol.asyncIterator]();
+  try {
+    let step = await iterator.next();
+    while (!step.done) {
+      collect(step, disposers);
+      step = await iterator.next();
+    }
+    collect(step, disposers);
+  } catch (error) {
+    await runDisposersReverse(disposers, 'unload');
+    throw error;
+  }
+  return (reason) => runDisposersReverse(disposers, reason);
+}

packages/agent-core-v2/src/_base/lifecycle/lifecycleMachine.ts

@@ -0,0 +1,235 @@
+export type LifecycleTransitionErrorReason =
+  | 'invalid_state'
+  | 'transition_conflict'
+  | 'missing_commit_state'
+  | 'missing_rollback_state'
+  | 'already_committed'
+  | 'already_rolled_back';
+
+export interface LifecycleTransitionErrorOptions<TState extends string> {
+  readonly reason: LifecycleTransitionErrorReason;
+  readonly operation: string;
+  readonly state: TState;
+  readonly expected?: TState | readonly TState[];
+  readonly activeOperation?: string;
+}
+
+export class LifecycleTransitionError<TState extends string = string> extends Error {
+  readonly reason: LifecycleTransitionErrorReason;
+  readonly operation: string;
+  readonly state: TState;
+  readonly expected?: TState | readonly TState[];
+  readonly activeOperation?: string;
+
+  constructor(options: LifecycleTransitionErrorOptions<TState>) {
+    super(formatTransitionError(options));
+    this.name = 'LifecycleTransitionError';
+    this.reason = options.reason;
+    this.operation = options.operation;
+    this.state = options.state;
+    this.expected = options.expected;
+    this.activeOperation = options.activeOperation;
+  }
+}
+
+export interface LifecycleSnapshot<TState extends string> {
+  readonly state: TState;
+  readonly transitioning: boolean;
+  readonly operation?: string;
+}
+
+export interface LifecycleSwitchOptions<TState extends string> {
+  readonly operation: string;
+  readonly from: TState | readonly TState[];
+  readonly to: TState;
+}
+
+export interface LifecycleTransactionOptions<TState extends string> {
+  readonly operation: string;
+  readonly from: TState | readonly TState[];
+  readonly enter: TState;
+  readonly commit?: TState;
+  readonly rollback?: TState;
+}
+
+export interface LifecycleTransaction<TState extends string> {
+  defer(callback: LifecycleAction): void;
+  rollback(callback: LifecycleAction): void;
+  afterCommit(callback: LifecycleAction): void;
+  commit(state: TState): void;
+  rollbackTo(state: TState): void;
+}
+
+export type LifecycleAction = () => void | Promise<void>;
+
+export class LifecycleMachine<TState extends string> {
+  private _state: TState;
+  private activeOperation: string | undefined;
+
+  constructor(initial: TState) {
+    this._state = initial;
+  }
+
+  get state(): TState {
+    return this._state;
+  }
+
+  get snapshot(): LifecycleSnapshot<TState> {
+    return this.activeOperation === undefined
+      ? { state: this._state, transitioning: false }
+      : {
+          state: this._state,
+          transitioning: true,
+          operation: this.activeOperation,
+        };
+  }
+
+  is(...states: readonly TState[]): boolean {
+    return states.includes(this._state);
+  }
+
+  switch(options: LifecycleSwitchOptions<TState>): void {
+    this.assertIdle(options.operation);
+    this.assertState(options.operation, options.from);
+    this._state = options.to;
+  }
+
+  async transaction<TResult>(
+    options: LifecycleTransactionOptions<TState>,
+    callback: (transaction: LifecycleTransaction<TState>) => TResult | Promise<TResult>,
+  ): Promise<TResult> {
+    this.assertIdle(options.operation);
+    this.assertState(options.operation, options.from);
+
+    this.activeOperation = options.operation;
+    this._state = options.enter;
+
+    const deferred: LifecycleAction[] = [];
+    const rollbacks: LifecycleAction[] = [];
+    const afterCommit: LifecycleAction[] = [];
+    let commitState = options.commit;
+    let rollbackState = options.rollback;
+    let commitSelected = false;
+    let rollbackSelected = false;
+
+    const transaction: LifecycleTransaction<TState> = {
+      defer: (action) => deferred.push(action),
+      rollback: (action) => rollbacks.push(action),
+      afterCommit: (action) => afterCommit.push(action),
+      commit: (state) => {
+        if (commitSelected) {
+          throw this.createError(options.operation, 'already_committed');
+        }
+        commitSelected = true;
+        commitState = state;
+      },
+      rollbackTo: (state) => {
+        if (rollbackSelected) {
+          throw this.createError(options.operation, 'already_rolled_back');
+        }
+        rollbackSelected = true;
+        rollbackState = state;
+      },
+    };
+
+    try {
+      let result: TResult;
+      try {
+        result = await callback(transaction);
+      } catch (error) {
+        const errors: unknown[] = [
+          error,
+          ...(await runActions(rollbacks)),
+          ...(await runActions(deferred)),
+        ];
+
+        if (rollbackState === undefined) {
+          errors.push(this.createError(options.operation, 'missing_rollback_state'));
+        } else {
+          this._state = rollbackState;
+        }
+        throw aggregateErrors(errors, `Lifecycle transaction "${options.operation}" failed`);
+      }
+
+      if (commitState === undefined) {
+        throw this.createError(options.operation, 'missing_commit_state');
+      }
+
+      const cleanupErrors = await runActions(deferred);
+      this._state = commitState;
+      const afterCommitErrors = await runActions(afterCommit);
+      const errors = [...cleanupErrors, ...afterCommitErrors];
+      if (errors.length > 0) {
+        throw aggregateErrors(
+          errors,
+          `Lifecycle transaction "${options.operation}" committed with action failures`,
+        );
+      }
+      return result;
+    } finally {
+      this.activeOperation = undefined;
+    }
+  }
+
+  private assertIdle(operation: string): void {
+    if (this.activeOperation === undefined) return;
+    throw this.createError(operation, 'transition_conflict', undefined, this.activeOperation);
+  }
+
+  private assertState(operation: string, expected: TState | readonly TState[]): void {
+    const states = Array.isArray(expected) ? expected : [expected];
+    if (states.includes(this._state)) return;
+    throw this.createError(operation, 'invalid_state', expected);
+  }
+
+  private createError(
+    operation: string,
+    reason: LifecycleTransitionErrorReason,
+    expected?: TState | readonly TState[],
+    activeOperation?: string,
+  ): LifecycleTransitionError<TState> {
+    return new LifecycleTransitionError({
+      reason,
+      operation,
+      state: this._state,
+      expected,
+      activeOperation,
+    });
+  }
+}
+
+async function runActions(actions: readonly LifecycleAction[]): Promise<unknown[]> {
+  const errors: unknown[] = [];
+  for (let index = actions.length - 1; index >= 0; index -= 1) {
+    try {
+      await actions[index]!();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  return errors;
+}
+
+function aggregateErrors(errors: readonly unknown[], message: string): unknown {
+  if (errors.length === 1) return errors[0];
+  return new AggregateError(errors, message, { cause: errors[0] });
+}
+
+function formatTransitionError<TState extends string>(
+  options: LifecycleTransitionErrorOptions<TState>,
+): string {
+  switch (options.reason) {
+    case 'invalid_state':
+      return `Lifecycle operation "${options.operation}" is not allowed from state "${options.state}"`;
+    case 'transition_conflict':
+      return `Lifecycle operation "${options.operation}" conflicts with active operation "${options.activeOperation}"`;
+    case 'missing_commit_state':
+      return `Lifecycle operation "${options.operation}" did not select a commit state`;
+    case 'missing_rollback_state':
+      return `Lifecycle operation "${options.operation}" did not select a rollback state`;
+    case 'already_committed':
+      return `Lifecycle operation "${options.operation}" already selected a commit state`;
+    case 'already_rolled_back':
+      return `Lifecycle operation "${options.operation}" already selected a rollback state`;
+  }
+}

packages/agent-core-v2/src/_base/log/fileLog.ts

@@ -0,0 +1,285 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { mkdir, open, rename, stat, unlink } from 'node:fs/promises';
+import { dirname } from 'pathe';
+
+import { formatEntry, type FormatOptions } from './formatter';
+import type { ILogWriter, LogEntry } from './log';
+
+export const PENDING_MAX = 1000;
+const STDERR_NOTICE_INTERVAL_MS = 30_000;
+
+class AsyncSerialQueue {
+  private tail: Promise<unknown> = Promise.resolve();
+
+  run<T>(task: () => Promise<T>): Promise<T> {
+    const next = this.tail.then(task, task);
+    this.tail = next.catch(() => {});
+    return next;
+  }
+}
+
+export interface RotatingFileWriterOptions {
+  readonly path: string;
+  readonly maxBytes: number;
+  readonly files: number;
+}
+
+async function syncDir(dirPath: string): Promise<void> {
+  if (process.platform === 'win32') return;
+  const dirFh = await open(dirPath, 'r');
+  try {
+    await dirFh.sync();
+  } finally {
+    await dirFh.close();
+  }
+}
+
+export class RotatingFileWriter {
+  private readonly queue = new AsyncSerialQueue();
+  private pending: string[] = [];
+  private dropped = 0;
+  private closed = false;
+  private lastStderrNotice = 0;
+  private currentBytes = -1;
+  private directorySynced = false;
+
+  constructor(private readonly options: RotatingFileWriterOptions) {}
+
+  enqueue(line: string): void {
+    if (this.closed) return;
+    if (this.pending.length >= PENDING_MAX) {
+      this.pending.shift();
+      this.dropped++;
+    }
+    this.pending.push(line);
+    this.scheduleDrain();
+  }
+
+  async flush(): Promise<boolean> {
+    return this.queue.run(() => this.drain());
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    try {
+      await this.flush();
+    } catch {
+    }
+  }
+
+  flushSync(): void {
+    if (this.closed || this.pending.length === 0) return;
+    try {
+      mkdirSync(dirname(this.options.path), { recursive: true });
+      const body = this.pending.join('') + this.takeDroppedNotice();
+      this.pending = [];
+      appendFileSync(this.options.path, body);
+    } catch (error) {
+      this.noteFailure(error);
+    }
+  }
+
+  private scheduleDrain(): void {
+    if (this.closed) return;
+    queueMicrotask(() => {
+      if (this.closed || this.pending.length === 0) return;
+      this.queue.run(() => this.drain()).catch(() => {});
+    });
+  }
+
+  private async drain(): Promise<boolean> {
+    if (this.pending.length === 0) return true;
+    const droppedLine = this.takeDroppedNotice();
+    const lines = droppedLine === '' ? [...this.pending] : [...this.pending, droppedLine];
+    this.pending = [];
+    try {
+      await mkdir(dirname(this.options.path), { recursive: true });
+      if (this.currentBytes < 0) {
+        this.currentBytes = await this.statSize(this.options.path);
+      }
+      await this.appendLines(lines);
+
+      if (!this.directorySynced) {
+        await syncDir(dirname(this.options.path));
+        this.directorySynced = true;
+      }
+
+      return true;
+    } catch (error) {
+      this.noteFailure(error);
+      this.restorePending(lines);
+      return false;
+    }
+  }
+
+  private restorePending(lines: readonly string[]): void {
+    const restored = [...lines, ...this.pending];
+    const overflow = restored.length - PENDING_MAX;
+    if (overflow <= 0) {
+      this.pending = restored;
+      return;
+    }
+    this.dropped += overflow;
+    this.pending = restored.slice(overflow);
+  }
+
+  private async appendLines(lines: readonly string[]): Promise<void> {
+    let chunk = '';
+    let chunkBytes = 0;
+    for (const line of lines) {
+      const lineBytes = Buffer.byteLength(line, 'utf-8');
+      if (
+        chunkBytes > 0 &&
+        (chunkBytes + lineBytes > this.options.maxBytes ||
+          this.currentBytes + chunkBytes + lineBytes > this.options.maxBytes)
+      ) {
+        await this.appendChunk(chunk);
+        chunk = '';
+        chunkBytes = 0;
+      }
+
+      if (
+        chunkBytes === 0 &&
+        this.currentBytes > 0 &&
+        this.currentBytes + lineBytes > this.options.maxBytes
+      ) {
+        await this.rotate();
+      }
+
+      chunk += line;
+      chunkBytes += lineBytes;
+    }
+    if (chunkBytes > 0) {
+      await this.appendChunk(chunk);
+    }
+  }
+
+  private async appendChunk(chunk: string): Promise<void> {
+    const fh = await open(this.options.path, 'a');
+    try {
+      await fh.appendFile(chunk, 'utf-8');
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    this.currentBytes += Buffer.byteLength(chunk, 'utf-8');
+    if (this.currentBytes >= this.options.maxBytes) {
+      await this.rotate();
+    }
+  }
+
+  private async rotate(): Promise<void> {
+    const { path, files } = this.options;
+    for (let i = files - 2; i >= 1; i--) {
+      const from = `${path}.${i}`;
+      const to = `${path}.${i + 1}`;
+      try {
+        await rename(from, to);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      }
+    }
+    try {
+      await rename(path, `${path}.1`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    try {
+      await unlink(`${path}.${files}`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    this.currentBytes = 0;
+    this.directorySynced = false;
+  }
+
+  private async statSize(p: string): Promise<number> {
+    try {
+      const s = await stat(p);
+      return s.size;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 0;
+      throw error;
+    }
+  }
+
+  private takeDroppedNotice(): string {
+    if (this.dropped === 0) return '';
+    const line = `... dropped ${this.dropped} entries ...\n`;
+    this.dropped = 0;
+    return line;
+  }
+
+  private noteFailure(error: unknown): void {
+    const now = Date.now();
+    if (now - this.lastStderrNotice < STDERR_NOTICE_INTERVAL_MS) return;
+    this.lastStderrNotice = now;
+    const code = (error as NodeJS.ErrnoException)?.code ?? 'UNKNOWN';
+    try {
+      process.stderr.write(`[logger] write failed: ${code}\n`);
+    } catch {}
+  }
+}
+
+export interface FileLogWriterOptions extends RotatingFileWriterOptions {
+  readonly format?: FormatOptions;
+}
+
+export class FileLogWriter implements ILogWriter {
+  private readonly sink: RotatingFileWriter;
+  private readonly format: FormatOptions;
+
+  constructor(options: FileLogWriterOptions) {
+    this.sink = new RotatingFileWriter(options);
+    this.format = options.format ?? {};
+  }
+
+  write(entry: LogEntry): void {
+    const { text, dropped } = formatEntry(entry, this.format);
+    if (dropped) return;
+    this.sink.enqueue(text + '\n');
+  }
+
+  async flush(): Promise<void> {
+    await this.sink.flush();
+  }
+
+  close(): Promise<void> {
+    return this.sink.close();
+  }
+
+  flushSync(): void {
+    this.sink.flushSync();
+  }
+}
+
+export function createFileLogWriter(options: FileLogWriterOptions): FileLogWriter {
+  return new FileLogWriter(options);
+}
+
+export class MemoryLogWriter implements ILogWriter {
+  readonly entries: LogEntry[] = [];
+  write(entry: LogEntry): void {
+    this.entries.push(entry);
+  }
+}
+
+export class ConsoleLogWriter implements ILogWriter {
+  write(entry: LogEntry): void {
+    const { text } = formatEntry(entry, { ansi: process.stderr.isTTY === true });
+    switch (entry.level) {
+      case 'error':
+        console.error(text);
+        break;
+      case 'warn':
+        console.warn(text);
+        break;
+      case 'debug':
+        console.debug(text);
+        break;
+      default:
+        console.log(text);
+    }
+  }
+}

packages/agent-core-v2/src/_base/log/formatter.ts

@@ -0,0 +1,196 @@
+import type { LogContext, LogEntry, LogEntryError } from './log';
+
+export const MSG_MAX_CHARS = 200;
+export const CTX_VALUE_MAX_CHARS = 2048;
+export const STACK_MAX_BYTES = 2048;
+export const ENTRY_MAX_BYTES = 4096;
+export const REDACT_MAX_DEPTH = 10;
+
+const REDACTED_KEYS: ReadonlySet<string> = new Set([
+  'authorization',
+  'apikey',
+  'token',
+  'refreshtoken',
+  'accesstoken',
+  'idtoken',
+  'password',
+  'secret',
+  'clientsecret',
+  'apisecret',
+  'cookie',
+  'setcookie',
+  'bearer',
+]);
+
+const SAFE_KEY_RE = /^[\w.-]+$/;
+const ELLIPSIS = '…';
+const TRUNCATED_TAIL = ` …truncated`;
+const REDACTED = '[REDACTED]';
+const RAW_SECRET_PATTERNS: readonly RegExp[] = [
+  /\b(authorization\s*[:=]\s*bearer\s+)[^\s"'`]+/gi,
+  /\b((?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|password|secret)\s*[:=]\s*)[^\s"'`]+/gi,
+  /\b(cookie\s*[:=]\s*)[^\r\n]+/gi,
+];
+
+const LEVEL_LABEL: Record<Exclude<LogEntry['level'], never>, string> = {
+  error: 'ERROR',
+  warn: 'WARN ',
+  info: 'INFO ',
+  debug: 'DEBUG',
+};
+
+const ANSI_LEVEL: Record<Exclude<LogEntry['level'], never>, string> = {
+  error: '',
+  warn: '',
+  info: '',
+  debug: '',
+};
+const ANSI_RESET = '';
+
+function normalizeKey(key: string): string {
+  return key.toLowerCase().replaceAll(/[_\-.]/g, '');
+}
+
+export function redactCtx(ctx: LogContext): LogContext {
+  const seen = new WeakSet<object>();
+  const walk = (value: unknown, depth: number): unknown => {
+    if (depth > REDACT_MAX_DEPTH) return '[REDACTED:depth]';
+    if (value === null || typeof value !== 'object') return value;
+    if (seen.has(value)) return '[REDACTED:cycle]';
+    seen.add(value);
+    if (Array.isArray(value)) {
+      return value.map((item) => walk(item, depth + 1));
+    }
+    const out: Record<string, unknown> = {};
+    for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = REDACTED_KEYS.has(normalizeKey(key)) ? REDACTED : walk(raw, depth + 1);
+    }
+    return out;
+  };
+  return walk(ctx, 0) as LogContext;
+}
+
+export interface FormatOptions {
+  readonly ansi?: boolean;
+  readonly omitContextKeys?: readonly string[];
+}
+
+export interface FormattedEntry {
+  readonly text: string;
+  readonly dropped: boolean;
+}
+
+function truncate(value: string, max: number): string {
+  return value.length <= max ? value : value.slice(0, max - 1) + ELLIPSIS;
+}
+
+function serializeValue(raw: unknown): string {
+  if (typeof raw === 'string') return redactString(raw);
+  if (raw === undefined) return 'undefined';
+  if (raw === null) return 'null';
+  if (
+    typeof raw === 'number' ||
+    typeof raw === 'boolean' ||
+    typeof raw === 'bigint' ||
+    typeof raw === 'symbol'
+  ) {
+    return String(raw);
+  }
+  try {
+    const json = JSON.stringify(raw);
+    if (json !== undefined) return json;
+  } catch {
+  }
+  if (typeof raw === 'function') return raw.name === '' ? '[Function]' : `[Function: ${raw.name}]`;
+  return Object.prototype.toString.call(raw);
+}
+
+function redactString(value: string): string {
+  let out = value;
+  for (const pattern of RAW_SECRET_PATTERNS) {
+    out = out.replace(pattern, `$1${REDACTED}`);
+  }
+  return out;
+}
+
+function quote(value: string): string {
+  return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n')}"`;
+}
+
+function formatPair(key: string, raw: unknown): string {
+  const limited = truncate(serializeValue(raw), CTX_VALUE_MAX_CHARS);
+  const renderedKey = SAFE_KEY_RE.test(key) ? key : quote(key);
+  const renderedVal = /[\s="\\]/.test(limited) || limited.length === 0 ? quote(limited) : limited;
+  return `${renderedKey}=${renderedVal}`;
+}
+
+function clipBytes(text: string, maxBytes: number): string {
+  if (Buffer.byteLength(text, 'utf-8') <= maxBytes) return text;
+  let lo = 0;
+  let hi = text.length;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (
+      Buffer.byteLength(text.slice(0, mid), 'utf-8') <=
+      maxBytes - Buffer.byteLength(TRUNCATED_TAIL, 'utf-8')
+    ) {
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return text.slice(0, lo) + TRUNCATED_TAIL;
+}
+
+function clipStack(stack: string): string {
+  if (Buffer.byteLength(stack, 'utf-8') <= STACK_MAX_BYTES) return stack;
+  return clipBytes(stack, STACK_MAX_BYTES);
+}
+
+function indentStack(stack: string): string {
+  return stack
+    .split('\n')
+    .map((line, i) => (i === 0 ? `  ${line}` : `    ${line.trimStart()}`))
+    .join('\n');
+}
+
+export function formatEntry(entry: LogEntry, options: FormatOptions = {}): FormattedEntry {
+  const ctx = entry.ctx ? redactCtx(entry.ctx) : undefined;
+  const omitContextKeys = new Set(options.omitContextKeys ?? []);
+  const msg = truncate(entry.msg, MSG_MAX_CHARS);
+  const pairs: string[] = [];
+  if (ctx) {
+    for (const [k, v] of Object.entries(ctx)) {
+      if (omitContextKeys.has(k)) continue;
+      if (v !== undefined) pairs.push(formatPair(k, v));
+    }
+  }
+
+  const time = new Date(entry.t).toISOString();
+  const label = LEVEL_LABEL[entry.level];
+  const rendered = pairs.length === 0
+    ? `${time} ${label} ${msg}`
+    : `${time} ${label} ${msg}  ${pairs.join(' ')}`;
+
+  let head = Buffer.byteLength(rendered, 'utf-8') > ENTRY_MAX_BYTES
+    ? clipBytes(rendered, ENTRY_MAX_BYTES)
+    : rendered;
+
+  if (options.ansi === true) {
+    head = `${ANSI_LEVEL[entry.level]}${head}${ANSI_RESET}`;
+  }
+
+  if (entry.error?.stack) {
+    head = `${head}\n${indentStack(clipStack(redactString(entry.error.stack)))}`;
+  } else if (entry.error?.message) {
+    head = `${head}\n  Error: ${redactString(entry.error.message)}`;
+  }
+
+  return { text: head, dropped: false };
+}
+
+export function extractError(value: Error): LogEntryError {
+  return typeof value.stack === 'string'
+    ? { message: value.message, stack: value.stack }
+    : { message: value.message };
+}

packages/agent-core-v2/src/_base/log/log.ts

@@ -0,0 +1,59 @@
+import { createDecorator, type ServiceIdentifier } from '#/_base/di/instantiation';
+
+export type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug';
+
+export type LogContext = Record<string, unknown>;
+
+export type LogPayload = unknown;
+
+export interface LogEntryError {
+  readonly message: string;
+  readonly stack?: string;
+}
+
+export interface LogEntry {
+  readonly t: number;
+  readonly level: Exclude<LogLevel, 'off'>;
+  readonly msg: string;
+  readonly ctx?: LogContext;
+  readonly error?: LogEntryError;
+}
+
+export interface ILogWriter {
+  write(entry: LogEntry): void;
+  flush?(): Promise<void>;
+  close?(): Promise<void>;
+  flushSync?(): void;
+}
+
+export interface ILogger {
+  error(message: string, payload?: LogPayload): void;
+  warn(message: string, payload?: LogPayload): void;
+  info(message: string, payload?: LogPayload): void;
+  debug(message: string, payload?: LogPayload): void;
+  child(ctx: LogContext): ILogger;
+}
+
+export interface ILogService extends ILogger {
+  readonly _serviceBrand: undefined;
+
+  readonly level: LogLevel;
+  setLevel(level: LogLevel): void;
+  flush(): Promise<void>;
+}
+
+export const ILogService: ServiceIdentifier<ILogService> =
+  createDecorator<ILogService>('logService');
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  off: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+};
+
+export function levelEnabled(level: LogLevel, configured: LogLevel): boolean {
+  if (level === 'off' || configured === 'off') return false;
+  return LEVEL_ORDER[level] <= LEVEL_ORDER[configured];
+}

packages/agent-core-v2/src/_base/log/logConfig.ts

@@ -0,0 +1,72 @@
+import { join } from 'pathe';
+
+import { createDecorator, type ServiceIdentifier } from '#/_base/di/instantiation';
+import type { ScopeSeed } from '#/_base/di/scope';
+
+import type { LogLevel } from './log';
+
+export const DEFAULT_LOG_LEVEL: LogLevel = 'info';
+export const DEFAULT_GLOBAL_MAX_BYTES = 6 * 1024 * 1024;
+export const DEFAULT_GLOBAL_FILES = 5;
+export const DEFAULT_SESSION_MAX_BYTES = 5 * 1024 * 1024;
+export const DEFAULT_SESSION_FILES = 3;
+
+export interface LoggingConfig {
+  readonly level: LogLevel;
+  readonly globalLogPath: string;
+  readonly globalMaxBytes: number;
+  readonly globalFiles: number;
+  readonly sessionMaxBytes: number;
+  readonly sessionFiles: number;
+}
+
+export interface ILogOptions extends LoggingConfig {}
+
+export const ILogOptions: ServiceIdentifier<ILogOptions> =
+  createDecorator<ILogOptions>('logOptions');
+
+export interface ResolveLoggingInput {
+  readonly homeDir: string;
+  readonly env: NodeJS.ProcessEnv;
+}
+
+export function resolveGlobalLogPath(homeDir: string): string {
+  return join(homeDir, 'logs', 'kimi-code.log');
+}
+
+export function resolveSessionLogPath(sessionDir: string): string {
+  return join(sessionDir, 'logs', 'kimi-code.log');
+}
+
+export function resolveLoggingConfig(input: ResolveLoggingInput): LoggingConfig {
+  const env = input.env;
+  return {
+    level: parseLevel(env['KIMI_LOG_LEVEL']) ?? DEFAULT_LOG_LEVEL,
+    globalLogPath: resolveGlobalLogPath(input.homeDir),
+    globalMaxBytes: parsePositiveInt(env['KIMI_LOG_GLOBAL_MAX_BYTES']) ?? DEFAULT_GLOBAL_MAX_BYTES,
+    globalFiles: parsePositiveInt(env['KIMI_LOG_GLOBAL_FILES']) ?? DEFAULT_GLOBAL_FILES,
+    sessionMaxBytes:
+      parsePositiveInt(env['KIMI_LOG_SESSION_MAX_BYTES']) ?? DEFAULT_SESSION_MAX_BYTES,
+    sessionFiles: parsePositiveInt(env['KIMI_LOG_SESSION_FILES']) ?? DEFAULT_SESSION_FILES,
+  };
+}
+
+export function logSeed(config: LoggingConfig): ScopeSeed {
+  return [
+    [ILogOptions as ServiceIdentifier<unknown>, config satisfies ILogOptions],
+  ];
+}
+
+function parseLevel(value: string | undefined): LogLevel | undefined {
+  if (value === undefined) return undefined;
+  const v = value.toLowerCase().trim();
+  if (v === 'off' || v === 'error' || v === 'warn' || v === 'info' || v === 'debug') return v;
+  return undefined;
+}
+
+function parsePositiveInt(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const n = Number.parseInt(value, 10);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  return n;
+}

packages/agent-core-v2/src/_base/log/logService.ts

@@ -0,0 +1,181 @@
+import { Service } from '#/_base/di/service';
+import { LifecycleScope } from '#/app/scopes';
+import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
+
+import {
+  type ILogger,
+  type ILogWriter,
+  type LogContext,
+  type LogEntry,
+  type LogEntryError,
+  type LogLevel,
+  type LogPayload,
+  ILogService,
+  levelEnabled,
+} from './log';
+import { createFileLogWriter, type FileLogWriter } from './fileLog';
+import { ILogOptions } from './logConfig';
+
+const pendingLogCloses = new Set<Promise<void>>();
+
+export function trackLogClose(close: Promise<void>): void {
+  const tracked = close.then(
+    () => undefined,
+    () => undefined,
+  );
+  pendingLogCloses.add(tracked);
+  void tracked.finally(() => pendingLogCloses.delete(tracked));
+}
+
+export async function drainLogCloses(): Promise<void> {
+  while (pendingLogCloses.size > 0) {
+    await Promise.all(pendingLogCloses);
+  }
+}
+
+interface ExtractedPayload {
+  readonly ctx?: LogContext;
+  readonly error?: LogEntryError;
+}
+
+function errorEntry(error: Error): LogEntryError {
+  return { message: error.message, stack: error.stack };
+}
+
+function stringifyPayload(payload: Exclude<LogPayload, undefined>): string {
+  if (typeof payload === 'string') return payload;
+  try {
+    const json = JSON.stringify(payload);
+    return json === undefined ? String(payload) : json;
+  } catch {
+    return String(payload);
+  }
+}
+
+function extractPayload(payload: LogPayload): ExtractedPayload | undefined {
+  if (payload === undefined) return {};
+  if (payload instanceof Error) return { error: errorEntry(payload) };
+  if (typeof payload === 'object' && payload !== null) {
+    let entries: [string, unknown][];
+    try {
+      entries = Object.entries(payload as Record<string, unknown>);
+    } catch {
+      return undefined;
+    }
+
+    let error: LogEntryError | undefined;
+    const ctx: LogContext = {};
+    for (const [key, value] of entries) {
+      if (key === 'error' && value instanceof Error) {
+        error = errorEntry(value);
+        continue;
+      }
+      ctx[key] = value;
+    }
+    return {
+      ...(Object.keys(ctx).length > 0 ? { ctx } : {}),
+      ...(error !== undefined ? { error } : {}),
+    };
+  }
+
+  return { ctx: { reason: stringifyPayload(payload) } };
+}
+
+export interface LogLevelState {
+  level: LogLevel;
+}
+
+export class BoundLogger extends Service implements ILogger {
+  constructor(
+    protected readonly writer: ILogWriter,
+    private readonly levelState: LogLevelState,
+    private readonly bound: LogContext = {},
+  ) {
+    super();
+  }
+
+  child(ctx: LogContext): ILogger {
+    return new BoundLogger(this.writer, this.levelState, { ...this.bound, ...ctx });
+  }
+
+  error(message: string, payload?: LogPayload): void {
+    this.emit('error', message, payload);
+  }
+  warn(message: string, payload?: LogPayload): void {
+    this.emit('warn', message, payload);
+  }
+  info(message: string, payload?: LogPayload): void {
+    this.emit('info', message, payload);
+  }
+  debug(message: string, payload?: LogPayload): void {
+    this.emit('debug', message, payload);
+  }
+
+  private emit(
+    level: Exclude<LogLevel, 'off'>,
+    message: string,
+    payload?: LogPayload,
+  ): void {
+    if (!levelEnabled(level, this.levelState.level)) return;
+    const extracted = extractPayload(payload);
+    if (extracted === undefined) return;
+    const payloadCtx = extracted.ctx;
+    const error = extracted.error;
+    const ctx =
+      payloadCtx !== undefined || Object.keys(this.bound).length > 0
+        ? { ...payloadCtx, ...this.bound }
+        : undefined;
+    const entry: LogEntry = {
+      t: Date.now(),
+      level,
+      msg: message,
+      ...(ctx !== undefined ? { ctx } : {}),
+      ...(error !== undefined ? { error } : {}),
+    };
+    this.writer.write(entry);
+  }
+}
+
+export class AppLogService extends BoundLogger implements ILogService {
+  declare readonly _serviceBrand: undefined;
+  private readonly sink: FileLogWriter;
+  private readonly rootLevel: LogLevelState;
+
+  constructor(@ILogOptions options: ILogOptions) {
+    const sink = createFileLogWriter({
+      path: options.globalLogPath,
+      maxBytes: options.globalMaxBytes,
+      files: options.globalFiles,
+    });
+    const rootLevel: LogLevelState = { level: options.level };
+    super(sink, rootLevel);
+    this.sink = sink;
+    this.rootLevel = rootLevel;
+  }
+
+  get level(): LogLevel {
+    return this.rootLevel.level;
+  }
+
+  setLevel(level: LogLevel): void {
+    this.rootLevel.level = level;
+  }
+
+  flush(): Promise<void> {
+    return this.sink.flush();
+  }
+
+  override dispose(): void {
+    this.sink.flushSync();
+    trackLogClose(this.sink.close());
+    super.dispose();
+  }
+}
+
+registerScopedService(
+  LifecycleScope.App,
+  ILogService,
+  AppLogService,
+  ScopeActivation.OnScopeCreated,
+  'log',
+);

packages/agent-core-v2/src/_base/state/stateRegistry.ts

@@ -0,0 +1,163 @@
+import { Disposable, type IDisposable, toDisposable } from '../di/lifecycle';
+import { BugIndicatingError } from '../errors/errors';
+import { Emitter, type Event } from '../event';
+
+export interface StateKey<T> {
+  readonly name: string;
+  readonly initial: () => T;
+  readonly snapshotExcluded?: boolean;
+}
+
+export interface StateChange {
+  readonly key: string;
+  readonly value: unknown;
+}
+
+export interface StateInspection {
+  readonly scope: string;
+  readonly state: Record<string, unknown>;
+  readonly parent?: StateInspection;
+}
+
+export interface IStateRegistry {
+  contributeState<T>(key: StateKey<T>): IDisposable;
+  has(key: StateKey<unknown>): boolean;
+  get<T>(key: StateKey<T>): T;
+  set<T>(key: StateKey<T>, value: T): void;
+  onDidChange<T>(key: StateKey<T>): Event<T>;
+  readonly onDidChangeAny: Event<StateChange>;
+  entries(): readonly [string, unknown][];
+  snapshot(): Record<string, unknown>;
+  inspect(): StateInspection;
+}
+
+export class StateRegistry extends Disposable implements IStateRegistry {
+  private readonly values = new Map<string, unknown>();
+  private readonly registrations = new Map<string, object>();
+  private readonly excludedFromSnapshot = new Set<string>();
+  private readonly keyEmitters = new Map<string, Emitter<unknown>>();
+  private readonly anyEmitter = this._register(new Emitter<StateChange>());
+  readonly onDidChangeAny: Event<StateChange> = this.anyEmitter.event;
+
+  protected readonly inspectScope: string = 'unknown';
+  protected inspectParent?: IStateRegistry;
+
+  contributeState<T>(key: StateKey<T>): IDisposable {
+    const replayable = (key as StateKey<T> & { readonly replayable?: unknown }).replayable;
+    if (typeof replayable === 'object' && replayable !== null) {
+      throw new BugIndicatingError(
+        `replayable state key '${key.name}' must be contributed to the Agent-scope state service`,
+      );
+    }
+    return this.contributeKey(key);
+  }
+
+  protected contributeKey<T>(key: StateKey<T>): IDisposable {
+    if (this.values.has(key.name)) {
+      throw new BugIndicatingError(`state key '${key.name}' is already registered`);
+    }
+    const registration = {};
+    this.registrations.set(key.name, registration);
+    this.values.set(key.name, key.initial());
+    if (key.snapshotExcluded === true) {
+      this.excludedFromSnapshot.add(key.name);
+    }
+    return toDisposable(() => {
+      if (this.registrations.get(key.name) !== registration) return;
+      this.registrations.delete(key.name);
+      this.values.delete(key.name);
+      this.excludedFromSnapshot.delete(key.name);
+      this.keyEmitters.get(key.name)?.dispose();
+      this.keyEmitters.delete(key.name);
+    });
+  }
+
+  has(key: StateKey<unknown>): boolean {
+    return this.values.has(key.name);
+  }
+
+  get<T>(key: StateKey<T>): T {
+    if (!this.values.has(key.name)) {
+      throw new BugIndicatingError(`state key '${key.name}' is not registered`);
+    }
+    return this.values.get(key.name) as T;
+  }
+
+  set<T>(key: StateKey<T>, value: T): void {
+    if (!this.values.has(key.name)) {
+      throw new BugIndicatingError(`state key '${key.name}' is not registered`);
+    }
+    this.values.set(key.name, value);
+    this.keyEmitters.get(key.name)?.fire(value);
+    this.anyEmitter.fire({ key: key.name, value });
+  }
+
+  onDidChange<T>(key: StateKey<T>): Event<T> {
+    let emitter = this.keyEmitters.get(key.name);
+    if (emitter === undefined) {
+      emitter = this._register(new Emitter<unknown>());
+      this.keyEmitters.set(key.name, emitter);
+    }
+    return emitter.event as Event<T>;
+  }
+
+  entries(): readonly [string, unknown][] {
+    return Array.from(this.values.entries());
+  }
+
+  snapshot(): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of this.values) {
+      if (this.excludedFromSnapshot.has(key)) continue;
+      out[key] = toJsonSafe(value, new WeakSet());
+    }
+    return out;
+  }
+
+  inspect(): StateInspection {
+    return {
+      scope: this.inspectScope,
+      state: this.snapshot(),
+      parent: this.inspectParent?.inspect(),
+    };
+  }
+}
+
+function toJsonSafe(value: unknown, seen: WeakSet<object>): unknown {
+  if (value === undefined || value === null) return null;
+  if (typeof value === 'function') return '(function)';
+  if (typeof value === 'bigint') return value.toString();
+  if (typeof value !== 'object') return value;
+  if (seen.has(value)) return '(circular)';
+  seen.add(value);
+  try {
+    if (value instanceof Date) return value.toJSON();
+    if (Array.isArray(value)) return value.map((item) => toJsonSafe(item, seen));
+    if (value instanceof Map) {
+      const entries = [...value.entries()];
+      const objectKeys = entries.every(([key]) => ['string', 'number'].includes(typeof key));
+      if (objectKeys) {
+        return Object.fromEntries(
+          entries.map(([key, item]) => [key, toJsonSafe(item, seen)] as const),
+        );
+      }
+      return entries.map(([key, item]) => [toJsonSafe(key, seen), toJsonSafe(item, seen)]);
+    }
+    if (value instanceof Set) {
+      return [...value.values()].map((item) => toJsonSafe(item, seen));
+    }
+    const proto: unknown = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+      const ctor = (value as { constructor?: { name?: string } }).constructor;
+      return `(${ctor?.name ?? 'object'})`;
+    }
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (typeof item === 'function') continue;
+      out[key] = toJsonSafe(item, seen);
+    }
+    return out;
+  } finally {
+    seen.delete(value);
+  }
+}

packages/agent-core-v2/src/_base/text/encoding.ts

@@ -0,0 +1,113 @@
+export type UtfTextEncoding = 'utf-8' | 'utf-16le' | 'utf-16be';
+
+export interface TextClassification {
+  readonly isBinary: boolean;
+  readonly encoding: UtfTextEncoding;
+}
+
+export const FS_BINARY_NONPRINTABLE_FRACTION = 0.3;
+
+export interface TextEncodingDetection {
+  readonly encoding: UtfTextEncoding;
+  readonly seemsBinary: boolean;
+}
+
+export const ENCODING_DETECTION_SAMPLE_BYTES = 512;
+
+const MIN_ZERO_BYTES_FOR_UTF16 = 2;
+
+const UTF16BE_BOM = [0xfe, 0xff] as const;
+const UTF16LE_BOM = [0xff, 0xfe] as const;
+const UTF8_BOM = [0xef, 0xbb, 0xbf] as const;
+
+function sniffTextEncoding(sample: Uint8Array): TextEncodingDetection {
+  if (sample.length >= 2) {
+    const b0 = sample[0]!;
+    const b1 = sample[1]!;
+    if (b0 === UTF16BE_BOM[0] && b1 === UTF16BE_BOM[1]) {
+      return { encoding: 'utf-16be', seemsBinary: false };
+    }
+    if (b0 === UTF16LE_BOM[0] && b1 === UTF16LE_BOM[1]) {
+      return { encoding: 'utf-16le', seemsBinary: false };
+    }
+    if (sample.length >= 3 && b0 === UTF8_BOM[0] && b1 === UTF8_BOM[1] && sample[2] === UTF8_BOM[2]) {
+      return { encoding: 'utf-8', seemsBinary: false };
+    }
+  }
+
+  let zerosAtOdd = 0;
+  let zerosAtEven = 0;
+  const limit = Math.min(sample.length, ENCODING_DETECTION_SAMPLE_BYTES);
+  for (let i = 0; i < limit; i++) {
+    if (sample[i] !== 0) continue;
+    if (i % 2 === 1) zerosAtOdd++;
+    else zerosAtEven++;
+  }
+
+  if (zerosAtOdd === 0 && zerosAtEven === 0) {
+    return { encoding: 'utf-8', seemsBinary: false };
+  }
+  if (zerosAtEven === 0 && zerosAtOdd >= MIN_ZERO_BYTES_FOR_UTF16) {
+    return { encoding: 'utf-16le', seemsBinary: false };
+  }
+  if (zerosAtOdd === 0 && zerosAtEven >= MIN_ZERO_BYTES_FOR_UTF16) {
+    return { encoding: 'utf-16be', seemsBinary: false };
+  }
+  return { encoding: 'utf-8', seemsBinary: true };
+}
+
+export function classifyTextSample(sample: Uint8Array): TextClassification {
+  const sniffed = sniffTextEncoding(sample);
+  if (sniffed.seemsBinary || sniffed.encoding !== 'utf-8') {
+    return { isBinary: sniffed.seemsBinary, encoding: sniffed.encoding };
+  }
+  if (sample.includes(0)) {
+    return { isBinary: true, encoding: 'utf-8' };
+  }
+  let end = sample.length;
+  for (let i = Math.max(0, sample.length - 3); i < sample.length; i++) {
+    const b = sample[i]!;
+    const expected =
+      b >= 0xc2 && b <= 0xdf ? 2 : b >= 0xe0 && b <= 0xef ? 3 : b >= 0xf0 && b <= 0xf4 ? 4 : 0;
+    if (expected === 0 || i + expected <= sample.length) continue;
+    let validPrefix = true;
+    for (let j = i + 1; j < sample.length; j++) {
+      const cb = sample[j]!;
+      if (cb < 0x80 || cb > 0xbf) {
+        validPrefix = false;
+        break;
+      }
+    }
+    if (validPrefix) {
+      end = i;
+      break;
+    }
+  }
+  let text: string;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(sample.subarray(0, end));
+  } catch {
+    return { isBinary: true, encoding: 'utf-8' };
+  }
+  let nonPrintable = 0;
+  let total = 0;
+  for (const ch of text) {
+    const cp = ch.codePointAt(0)!;
+    total++;
+    if (cp === 9 || cp === 10 || cp === 13) continue;
+    if (cp < 32 || (cp >= 0x7f && cp <= 0x9f)) nonPrintable++;
+  }
+  if (total > 0 && nonPrintable / total > FS_BINARY_NONPRINTABLE_FRACTION) {
+    return { isBinary: true, encoding: 'utf-8' };
+  }
+  return { isBinary: false, encoding: 'utf-8' };
+}
+
+export function detectTextEncoding(sample: Uint8Array): TextEncodingDetection {
+  const classification = classifyTextSample(sample);
+  return { encoding: classification.encoding, seemsBinary: classification.isBinary };
+}
+
+export function decodeUtfText(bytes: Uint8Array, encoding: UtfTextEncoding): string {
+  return new TextDecoder(encoding, { fatal: false }).decode(bytes);
+}

packages/agent-core-v2/src/_base/text/frontmatter.ts

@@ -0,0 +1,43 @@
+import { load as loadYaml } from 'js-yaml';
+
+export class FrontmatterError extends Error {
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = 'FrontmatterError';
+    if (cause !== undefined) {
+      Object.defineProperty(this, 'cause', { value: cause, configurable: true });
+    }
+  }
+}
+
+export interface ParsedFrontmatter {
+  readonly data: unknown;
+  readonly body: string;
+}
+
+const FENCE = '---';
+
+export function parseFrontmatter(text: string): ParsedFrontmatter {
+  const lines = text.split(/\r?\n/);
+  if (lines[0]?.trim() !== FENCE) {
+    return { data: null, body: text };
+  }
+
+  const close = lines.findIndex((line, index) => index > 0 && line.trim() === FENCE);
+  if (close === -1) {
+    throw new FrontmatterError('Missing closing frontmatter fence');
+  }
+
+  const yamlText = lines.slice(1, close).join('\n').trim();
+  const body = lines.slice(close + 1).join('\n');
+  if (yamlText === '') {
+    return { data: {}, body };
+  }
+
+  try {
+    return { data: loadYaml(yamlText) ?? {}, body };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new FrontmatterError(message, error);
+  }
+}

packages/agent-core-v2/src/_base/text/line-endings.ts

@@ -0,0 +1,67 @@
+export type LineEndingStyle = 'lf' | 'crlf' | 'mixed';
+
+export interface ModelTextView {
+  text: string;
+  lineEndingStyle: LineEndingStyle;
+}
+
+export function detectLineEndingStyle(text: string): LineEndingStyle {
+  let hasCrLf = false;
+  let hasLf = false;
+  let hasLoneCr = false;
+
+  for (let i = 0; i < text.length; i++) {
+    const code = text.codePointAt(i);
+    if (code === 13) {
+      if (text.codePointAt(i + 1) === 10) {
+        hasCrLf = true;
+        i++;
+      } else {
+        hasLoneCr = true;
+      }
+    } else if (code === 10) {
+      hasLf = true;
+    }
+  }
+
+  if (hasLoneCr || (hasCrLf && hasLf)) return 'mixed';
+  if (hasCrLf) return 'crlf';
+  return 'lf';
+}
+
+export function toModelTextView(raw: string): ModelTextView {
+  const lineEndingStyle = detectLineEndingStyle(raw);
+  if (lineEndingStyle !== 'crlf') {
+    return { text: raw, lineEndingStyle };
+  }
+
+  return {
+    text: raw.replaceAll('\r\n', '\n'),
+    lineEndingStyle,
+  };
+}
+
+export function materializeModelText(text: string, lineEndingStyle: LineEndingStyle): string {
+  if (lineEndingStyle !== 'crlf') return text;
+  return text.replaceAll('\r\n', '\n').replaceAll('\n', '\r\n');
+}
+
+export function makeCarriageReturnsVisible(text: string): string {
+  return text.replaceAll('\r', '\\r');
+}
+
+export function splitLinesKeepingTerminator(text: string): string[] {
+  if (text.length === 0) return [];
+  const lines: string[] = [];
+  let start = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    if (text.codePointAt(i) === 0x0a) {
+      lines.push(text.slice(start, i + 1));
+      start = i + 1;
+    }
+  }
+  if (start < text.length) {
+    lines.push(text.slice(start));
+  }
+  return lines;
+}

packages/agent-core-v2/src/_base/utils/abort.ts

@@ -0,0 +1,93 @@
+export function abortError(message = 'Aborted'): Error {
+  const error = new Error(message);
+  error.name = 'AbortError';
+  return error;
+}
+
+export function isAbortError(error: unknown): error is Error {
+  return error instanceof Error && error.name === 'AbortError';
+}
+
+export class UserCancellationError extends Error {
+  readonly userCancelled = true;
+
+  constructor() {
+    super('Aborted by the user');
+    this.name = 'AbortError';
+  }
+}
+
+export function userCancellationReason(): UserCancellationError {
+  return new UserCancellationError();
+}
+
+export function isUserCancellation(value: unknown): value is UserCancellationError {
+  return value instanceof UserCancellationError;
+}
+
+export function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(abortReason(signal));
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      reject(abortReason(signal));
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise.then(resolve, reject).finally(() => {
+      signal.removeEventListener('abort', onAbort);
+    });
+  });
+}
+
+export function linkAbortSignal(source: AbortSignal, target: AbortController): () => void {
+  const onAbort = () => {
+    target.abort(source.reason);
+  };
+  if (source.aborted) {
+    onAbort();
+    return () => {};
+  }
+  source.addEventListener('abort', onAbort, { once: true });
+  return () => {
+    source.removeEventListener('abort', onAbort);
+  };
+}
+
+function abortReason(signal: AbortSignal): Error {
+  if (signal.reason instanceof Error && !isDefaultAbortReason(signal.reason)) {
+    return signal.reason;
+  }
+  return abortError();
+}
+
+function isDefaultAbortReason(reason: Error): boolean {
+  return reason.name === 'AbortError' && reason.message === 'This operation was aborted';
+}
+
+export interface DeadlineAbortSignal {
+  readonly signal: AbortSignal;
+  readonly timedOut: () => boolean;
+  readonly clear: () => void;
+}
+
+export function createDeadlineAbortSignal(
+  source: AbortSignal,
+  timeoutMs: number,
+): DeadlineAbortSignal {
+  const controller = new AbortController();
+  const unlinkAbortSignal = linkAbortSignal(source, controller);
+  let didTimeout = false;
+  let timeout: ReturnType<typeof setTimeout> | undefined = setTimeout(() => {
+    didTimeout = true;
+    controller.abort(abortError());
+  }, timeoutMs);
+
+  return {
+    signal: controller.signal,
+    timedOut: () => didTimeout,
+    clear: () => {
+      if (timeout !== undefined) clearTimeout(timeout);
+      timeout = undefined;
+      unlinkAbortSignal();
+    },
+  };
+}

packages/agent-core-v2/src/_base/utils/canonical-args.ts

@@ -0,0 +1,24 @@
+export function canonicalTelemetryArgs(args: unknown): string {
+  const json = JSON.stringify(sortJsonValue(args));
+  return json ?? String(args);
+}
+
+function sortJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortJsonValue);
+  }
+  if (!isPlainRecord(value)) {
+    return value;
+  }
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(value).toSorted()) {
+    out[key] = sortJsonValue(value[key]);
+  }
+  return out;
+}
+
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}

packages/agent-core-v2/src/_base/utils/env.ts

@@ -0,0 +1,10 @@
+const TRUE_BOOLEAN_ENV_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_BOOLEAN_ENV_VALUES = new Set(['0', 'false', 'no', 'off']);
+
+export function parseBooleanEnv(value: string | undefined): boolean | undefined {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === undefined || normalized.length === 0) return undefined;
+  if (TRUE_BOOLEAN_ENV_VALUES.has(normalized)) return true;
+  if (FALSE_BOOLEAN_ENV_VALUES.has(normalized)) return false;
+  return undefined;
+}

packages/agent-core-v2/src/_base/utils/fileMeta.ts

@@ -0,0 +1,113 @@
+import { extname } from 'node:path';
+
+import { classifyTextSample } from '#/_base/text/encoding';
+
+export { FS_BINARY_NONPRINTABLE_FRACTION } from '#/_base/text/encoding';
+
+export const FS_BINARY_SAMPLE_BYTES = 4096;
+
+export interface FileMetaStat {
+  readonly size: number;
+  readonly mtimeMs?: number;
+  readonly ino?: number;
+}
+
+export function detectBinary(buf: Uint8Array): boolean {
+  return classifyTextSample(buf).isBinary;
+}
+
+export function countLines(text: string): number {
+  if (text.length === 0) return 0;
+  let n = 1;
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) n++;
+  }
+  if (text.charCodeAt(text.length - 1) === 10) n--;
+  return Math.max(0, n);
+}
+
+export function buildEtag(st: FileMetaStat): string {
+  const mtime = Math.floor(st.mtimeMs ?? 0);
+  const ino = st.ino ?? 0;
+  return [mtime.toString(36), st.size.toString(36), ino.toString(36)].join('-');
+}
+
+const EXT_TO_MIME: Readonly<Record<string, string>> = {
+  '.ts': 'text/typescript',
+  '.tsx': 'text/typescript',
+  '.js': 'text/javascript',
+  '.jsx': 'text/javascript',
+  '.mjs': 'text/javascript',
+  '.cjs': 'text/javascript',
+  '.json': 'application/json',
+  '.md': 'text/markdown',
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.pdf': 'application/pdf',
+  '.yaml': 'text/yaml',
+  '.yml': 'text/yaml',
+  '.toml': 'application/toml',
+  '.sh': 'text/x-shellscript',
+  '.py': 'text/x-python',
+  '.rs': 'text/rust',
+  '.go': 'text/x-go',
+};
+
+export function guessMime(path: string, isBinary: boolean): string {
+  const ext = extname(path).toLowerCase();
+  const mapped = EXT_TO_MIME[ext];
+  if (mapped !== undefined) return mapped;
+  return isBinary ? 'application/octet-stream' : 'text/plain';
+}
+
+const APPLICATION_TEXT_ALIASES: Readonly<Record<string, string>> = {
+  'application/javascript': 'text/javascript',
+  'application/x-javascript': 'text/javascript',
+  'application/ecmascript': 'text/javascript',
+  'application/yaml': 'text/yaml',
+  'application/x-yaml': 'text/yaml',
+  'application/sql': 'text/plain',
+  'application/graphql': 'text/plain',
+  'application/x-www-form-urlencoded': 'text/plain',
+};
+
+export function textExtensionForMime(mimeType: string): string | undefined {
+  const mime = mimeType.split(';')[0]!.trim().toLowerCase();
+  if (mime === 'application/json' || mime.endsWith('+json')) return '.json';
+  if (mime === 'application/xml' || mime.endsWith('+xml')) return '.xml';
+  if (mime.endsWith('+yaml')) return '.yaml';
+  if (mime === 'application/toml') return '.toml';
+  if (mime === 'text/csv') return '.csv';
+  const textMime = APPLICATION_TEXT_ALIASES[mime] ?? mime;
+  if (!textMime.startsWith('text/')) return undefined;
+  return Object.entries(EXT_TO_MIME).find(([, value]) => value === textMime)?.[0] ?? '.txt';
+}
+
+const EXT_TO_LANGUAGE: Readonly<Record<string, string>> = {
+  '.ts': 'typescript',
+  '.tsx': 'typescriptreact',
+  '.js': 'javascript',
+  '.jsx': 'javascriptreact',
+  '.mjs': 'javascript',
+  '.cjs': 'javascript',
+  '.json': 'json',
+  '.md': 'markdown',
+  '.html': 'html',
+  '.css': 'css',
+  '.yaml': 'yaml',
+  '.yml': 'yaml',
+  '.toml': 'toml',
+  '.sh': 'shellscript',
+  '.py': 'python',
+  '.rs': 'rust',
+  '.go': 'go',
+};
+
+export function guessLanguageId(path: string): string | undefined {
+  return EXT_TO_LANGUAGE[extname(path).toLowerCase()];
+}

packages/agent-core-v2/src/_base/utils/fs.ts

@@ -0,0 +1,168 @@
+import { randomBytes } from 'node:crypto';
+import { closeSync, fsyncSync, openSync } from 'node:fs';
+import * as nodeFs from 'node:fs';
+import { open, rename, unlink } from 'node:fs/promises';
+import { dirname } from 'pathe';
+
+export async function syncDir(dirPath: string): Promise<void> {
+  if (process.platform === 'win32') return;
+  const dirFh = await open(dirPath, 'r');
+  try {
+    await dirFh.sync();
+  } finally {
+    await dirFh.close();
+  }
+}
+
+export function syncDirSync(dirPath: string): void {
+  if (process.platform === 'win32') return;
+  const fd = openSync(dirPath, 'r');
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export async function writeFileAtomicDurable(
+  filePath: string,
+  content: string | Uint8Array,
+): Promise<void> {
+  const tmpPath = filePath + '.tmp';
+  let renamed = false;
+  try {
+    const fh = await open(tmpPath, 'w');
+    try {
+      await fh.writeFile(content);
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    if (process.platform === 'win32') {
+      try {
+        await unlink(filePath);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== 'ENOENT') throw error;
+      }
+    }
+    await rename(tmpPath, filePath);
+    renamed = true;
+    await syncDir(dirname(filePath));
+  } finally {
+    if (!renamed) {
+      try {
+        await unlink(tmpPath);
+      } catch {
+      }
+    }
+  }
+}
+
+function syncFd(fd: number): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    nodeFs.fsync(fd, (err) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+export async function atomicWrite(
+  filePath: string,
+  content: string | Uint8Array,
+  _syncOverride?: (fd: number) => Promise<void>,
+  mode?: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  signal?.throwIfAborted();
+  const hex = randomBytes(4).toString('hex');
+  const tmpPath = `${filePath}.tmp.${process.pid}.${hex}`;
+  let renamed = false;
+  try {
+    const fh = await open(tmpPath, 'w', mode);
+    try {
+      signal?.throwIfAborted();
+      await fh.writeFile(content);
+      signal?.throwIfAborted();
+      await (_syncOverride ?? syncFd)(fh.fd);
+    } finally {
+      await fh.close();
+    }
+    if (process.platform === 'win32') {
+      try {
+        await unlink(filePath);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== 'ENOENT') throw error;
+      }
+    }
+    signal?.throwIfAborted();
+    await rename(tmpPath, filePath);
+    renamed = true;
+  } finally {
+    if (!renamed) {
+      try {
+        await unlink(tmpPath);
+      } catch {
+      }
+    }
+  }
+}
+
+export async function atomicWriteStream(
+  filePath: string,
+  source: AsyncIterable<Uint8Array>,
+  mode?: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  signal?.throwIfAborted();
+  const hex = randomBytes(4).toString('hex');
+  const tmpPath = `${filePath}.tmp.${process.pid}.${hex}`;
+  let renamed = false;
+  const destroyable = source as AsyncIterable<Uint8Array> & {
+    destroy?(error?: Error): void;
+  };
+  const onAbort = (): void => {
+    const reason = signal?.reason instanceof Error ? signal.reason : undefined;
+    destroyable.destroy?.(reason);
+  };
+  signal?.addEventListener('abort', onAbort, { once: true });
+  try {
+    const fh = await open(tmpPath, 'w', mode);
+    try {
+      for await (const chunk of source) {
+        signal?.throwIfAborted();
+        if (chunk.byteLength > 0) {
+          await fh.writeFile(chunk);
+        }
+      }
+      signal?.throwIfAborted();
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    if (process.platform === 'win32') {
+      try {
+        await unlink(filePath);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== 'ENOENT') throw error;
+      }
+    }
+    signal?.throwIfAborted();
+    await rename(tmpPath, filePath);
+    renamed = true;
+  } finally {
+    signal?.removeEventListener('abort', onAbort);
+    if (!renamed) {
+      try {
+        await unlink(tmpPath);
+      } catch {
+      }
+    }
+  }
+}

packages/agent-core-v2/src/_base/utils/hero-slug.ts

@@ -0,0 +1,263 @@
+import { randomInt } from 'node:crypto';
+
+export const HERO_NAMES = [
+  'iron-man',
+  'spider-man',
+  'captain-america',
+  'thor',
+  'hulk',
+  'black-widow',
+  'hawkeye',
+  'black-panther',
+  'doctor-strange',
+  'scarlet-witch',
+  'vision',
+  'falcon',
+  'war-machine',
+  'ant-man',
+  'wasp',
+  'captain-marvel',
+  'gamora',
+  'star-lord',
+  'groot',
+  'rocket',
+  'drax',
+  'mantis',
+  'nebula',
+  'shang-chi',
+  'moon-knight',
+  'ms-marvel',
+  'she-hulk',
+  'echo',
+  'wolverine',
+  'cyclops',
+  'storm',
+  'jean-grey',
+  'rogue',
+  'beast',
+  'nightcrawler',
+  'colossus',
+  'shadowcat',
+  'jubilee',
+  'cable',
+  'deadpool',
+  'bishop',
+  'magik',
+  'iceman',
+  'archangel',
+  'psylocke',
+  'dazzler',
+  'forge',
+  'havok',
+  'polaris',
+  'emma-frost',
+  'namor',
+  'silver-surfer',
+  'adam-warlock',
+  'nova',
+  'quasar',
+  'sentry',
+  'blue-marvel',
+  'spectrum',
+  'squirrel-girl',
+  'cloak',
+  'dagger',
+  'punisher',
+  'elektra',
+  'luke-cage',
+  'iron-fist',
+  'jessica-jones',
+  'daredevil',
+  'blade',
+  'ghost-rider',
+  'morbius',
+  'venom',
+  'carnage',
+  'silk',
+  'spider-gwen',
+  'miles-morales',
+  'america-chavez',
+  'kate-bishop',
+  'yelena-belova',
+  'white-tiger',
+  'moon-girl',
+  'devil-dinosaur',
+  'amadeus-cho',
+  'riri-williams',
+  'kamala-khan',
+  'sam-alexander',
+  'nova-prime',
+  'medusa',
+  'black-bolt',
+  'crystal',
+  'karnak',
+  'gorgon',
+  'lockjaw',
+  'quake',
+  'mockingbird',
+  'bobbi-morse',
+  'maria-hill',
+  'nick-fury',
+  'phil-coulson',
+  'winter-soldier',
+  'us-agent',
+  'patriot',
+  'speed',
+  'wiccan',
+  'hulkling',
+  'stature',
+  'yellowjacket',
+  'tigra',
+  'hellcat',
+  'valkyrie',
+  'sif',
+  'beta-ray-bill',
+  'hercules',
+  'wonder-man',
+  'taskmaster',
+  'domino',
+  'cannonball',
+  'sunspot',
+  'wolfsbane',
+  'warpath',
+  'multiple-man',
+  'banshee',
+  'siryn',
+  'monet',
+  'rictor',
+  'shatterstar',
+  'longshot',
+  'daken',
+  'x-23',
+  'fantomex',
+  'batman',
+  'superman',
+  'wonder-woman',
+  'flash',
+  'aquaman',
+  'green-lantern',
+  'martian-manhunter',
+  'cyborg',
+  'hawkgirl',
+  'green-arrow',
+  'black-canary',
+  'zatanna',
+  'constantine',
+  'shazam',
+  'blue-beetle',
+  'booster-gold',
+  'firestorm',
+  'atom',
+  'hawkman',
+  'plastic-man',
+  'red-tornado',
+  'starfire',
+  'raven',
+  'beast-boy',
+  'robin',
+  'nightwing',
+  'batgirl',
+  'batwoman',
+  'red-hood',
+  'signal',
+  'orphan',
+  'spoiler',
+  'catwoman',
+  'huntress',
+  'supergirl',
+  'superboy',
+  'power-girl',
+  'steel',
+  'stargirl',
+  'wildcat',
+  'doctor-fate',
+  'mister-terrific',
+  'hourman',
+  'sandman',
+  'spectre',
+  'phantom-stranger',
+  'swamp-thing',
+  'animal-man',
+  'deadman',
+  'vixen',
+  'black-lightning',
+  'static',
+  'icon',
+  'rocket-dc',
+  'captain-atom',
+  'fire',
+  'ice',
+  'elongated-man',
+  'metamorpho',
+  'black-hawk',
+  'crimson-avenger',
+  'doctor-mid-nite',
+  'jakeem-thunder',
+  'mister-miracle',
+  'big-barda',
+  'orion',
+  'lightray',
+  'forager',
+  'killer-frost',
+  'jessica-cruz',
+  'simon-baz',
+  'john-stewart',
+  'guy-gardner',
+  'kyle-rayner',
+  'hal-jordan',
+  'wally-west',
+  'barry-allen',
+  'jay-garrick',
+  'impulse',
+  'kid-flash',
+  'donna-troy',
+  'tempest',
+  'aqualad',
+  'miss-martian',
+  'terra',
+  'jericho',
+  'ravager',
+  'red-star',
+  'pantha',
+  'argent',
+  'damage',
+  'jade',
+  'obsidian',
+  'cyclone',
+  'atom-smasher',
+  'maxima',
+  'starman',
+  'liberty-belle',
+  'dove',
+  'hawk',
+  'blue-devil',
+  'creeper',
+  'ragman',
+  'thunder',
+] as const satisfies readonly [string, ...string[]];
+
+const MAX_ATTEMPTS = 20;
+
+function pickHero(): string {
+  return HERO_NAMES[randomInt(HERO_NAMES.length)]!;
+}
+
+function assembleSlug(): string {
+  return `${pickHero()}-${pickHero()}-${pickHero()}`;
+}
+
+export function generateHeroSlug(id: string, existing: Set<string>): string {
+  let slug = '';
+  let collided = true;
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    slug = assembleSlug();
+    if (!existing.has(slug)) {
+      collided = false;
+      break;
+    }
+  }
+  if (collided) {
+    slug = `${slug}-${id.slice(0, 8)}`;
+  }
+  return slug;
+}