@archships/dim-agent-sdk 0.0.1 → 0.0.3

package/dist/index.js

@@ -208,27 +208,60 @@ function isHookControlResult(value) {
   const candidate = value;
   return (candidate.type === "continue" || candidate.type === "replace" || candidate.type === "stop") && "payload" in candidate;
 }
+function isToolBeforeExecuteControlResult(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const candidate = value;
+  return candidate.type === "allow" || candidate.type === "deny" || candidate.type === "ask" || candidate.type === "replaceToolCall" || candidate.type === "provideResult";
+}
+function isNotificationControlResult(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const candidate = value;
+  return candidate.type === "continue" || candidate.type === "replace" || candidate.type === "suppress";
+}
+function isRunStopControlResult(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const candidate = value;
+  return candidate.type === "continue" || candidate.type === "finalize";
+}
 
 // src/plugin-host/HookPipeline.ts
 class HookPipeline {
   registrations = [];
-  register(pluginId, priority, hooks) {
+  nextOrder = 0;
+  register(pluginId, pluginPriority, hooks, services) {
     if (!hooks)
       return;
-    if (hooks["model.event"]?.middleware && hooks["model.event"]?.middleware.length > 0)
-      throw new Error(`Plugin ${pluginId} cannot register middleware for model.event`);
-    this.registrations.push({ pluginId, priority, hooks });
-    this.registrations.sort((left, right) => right.priority - left.priority);
+    for (const entry of hooks) {
+      if (!entry.middleware?.length && !entry.observers?.length)
+        continue;
+      if (entry.descriptor.name === "model.event" && entry.middleware && entry.middleware.length > 0)
+        throw new Error(`Plugin ${pluginId} cannot register middleware for model.event`);
+      if (entry.descriptor.mode === "async" && entry.middleware && entry.middleware.length > 0)
+        throw new Error(`Plugin ${pluginId} cannot register async middleware for ${entry.descriptor.name}`);
+      this.registrations.push({
+        pluginId,
+        order: this.nextOrder++,
+        priority: entry.descriptor.priority ?? pluginPriority,
+        descriptor: entry.descriptor,
+        services,
+        middleware: [...entry.middleware ?? []],
+        observers: [...entry.observers ?? []]
+      });
+    }
+    this.registrations.sort((left, right) => {
+      if (left.priority !== right.priority)
+        return right.priority - left.priority;
+      return left.order - right.order;
+    });
   }
   async runMiddleware(name, payload, context) {
     let current = payload;
-    for (const registration of this.registrations) {
-      const middlewares = registration.hooks[name]?.middleware ?? [];
-      for (const middleware of middlewares) {
-        const result = await middleware({
-          payload: current,
-          context: { ...context, metadata: { ...context.metadata, pluginId: registration.pluginId } }
-        });
+    for (const registration of this.matchingRegistrations(name, current)) {
+      for (const middleware of registration.middleware) {
+        const result = await this.runMiddlewareHandler(registration, middleware, current, context);
         if (result === undefined)
           continue;
         if (isHookControlResult(result)) {
@@ -237,22 +270,191 @@ class HookPipeline {
             return current;
           continue;
         }
+        if (isNotificationControlResult(result) || isRunStopControlResult(result) || isToolBeforeExecuteControlResult(result))
+          throw new Error(`Hook ${registration.descriptor.name} returned an unsupported control result`);
         current = result;
       }
     }
     return current;
   }
+  async runToolBeforeExecute(payload, context) {
+    let current = payload;
+    for (const registration of this.matchingRegistrations("tool.beforeExecute", current)) {
+      for (const middleware of registration.middleware) {
+        const result = await this.runMiddlewareHandler(registration, middleware, current, context);
+        if (result === undefined)
+          continue;
+        if (isHookControlResult(result)) {
+          current = result.payload;
+          if (result.type === "stop")
+            return { payload: current };
+          continue;
+        }
+        if (isToolBeforeExecuteControlResult(result)) {
+          if (result.type === "replaceToolCall") {
+            current = { ...current, toolCall: result.toolCall };
+            continue;
+          }
+          if (result.type === "ask" && result.toolCall)
+            current = { ...current, toolCall: result.toolCall };
+          return { payload: current, control: result };
+        }
+        current = result;
+      }
+    }
+    return { payload: current };
+  }
+  async runNotifyMessage(payload, context) {
+    let current = payload;
+    for (const registration of this.matchingRegistrations("notify.message", current)) {
+      for (const middleware of registration.middleware) {
+        const result = await this.runMiddlewareHandler(registration, middleware, current, context);
+        if (result === undefined)
+          continue;
+        if (isHookControlResult(result)) {
+          current = result.payload;
+          if (result.type === "stop")
+            return { payload: current };
+          continue;
+        }
+        if (isNotificationControlResult(result)) {
+          if (result.type === "replace") {
+            current = { ...current, notification: result.notification };
+            continue;
+          }
+          if (result.type === "suppress")
+            return { payload: current, suppressed: true };
+          continue;
+        }
+        current = result;
+      }
+    }
+    return { payload: current };
+  }
+  async runRunStop(payload, context) {
+    let current = payload;
+    for (const registration of this.matchingRegistrations("run.stop", current)) {
+      for (const middleware of registration.middleware) {
+        const result = await this.runMiddlewareHandler(registration, middleware, current, context);
+        if (result === undefined)
+          continue;
+        if (isHookControlResult(result)) {
+          current = result.payload;
+          if (result.type === "stop")
+            return { payload: current };
+          continue;
+        }
+        if (isRunStopControlResult(result))
+          return { payload: current, control: result };
+        current = result;
+      }
+    }
+    return { payload: current };
+  }
   async runObservers(name, payload, context) {
-    for (const registration of this.registrations) {
-      const observers = registration.hooks[name]?.observers ?? [];
-      for (const observer of observers) {
-        await observer({
-          payload,
-          context: { ...context, metadata: { ...context.metadata, pluginId: registration.pluginId } }
-        });
+    for (const registration of this.matchingRegistrations(name, payload)) {
+      for (const observer of registration.observers) {
+        const task = this.runObserverHandler(registration, observer, payload, context);
+        if (registration.descriptor.mode === "async") {
+          task.catch(() => {});
+          continue;
+        }
+        await task.catch(() => {});
       }
     }
   }
+  matchingRegistrations(name, payload) {
+    return this.registrations.filter((registration) => {
+      return registration.descriptor.name === name && matchesHookDescriptor(registration.descriptor, payload);
+    });
+  }
+  async runMiddlewareHandler(registration, middleware, payload, context) {
+    const task = Promise.resolve(middleware({
+      payload,
+      context: this.withHandlerMetadata(context, registration)
+    }));
+    return await withTimeout(task, registration.descriptor.timeoutMs, () => {
+      return new Error(`Hook ${registration.descriptor.name} for plugin ${registration.pluginId} timed out after ${registration.descriptor.timeoutMs}ms`);
+    });
+  }
+  async runObserverHandler(registration, observer, payload, context) {
+    const task = Promise.resolve(observer({
+      payload,
+      context: this.withHandlerMetadata(context, registration)
+    }));
+    await withTimeout(task, registration.descriptor.timeoutMs, () => {
+      return new Error(`Hook ${registration.descriptor.name} for plugin ${registration.pluginId} timed out after ${registration.descriptor.timeoutMs}ms`);
+    });
+  }
+  withHandlerMetadata(context, registration) {
+    return {
+      ...context,
+      services: registration.services ?? context.services,
+      status: context.status ? structuredClone(context.status) : undefined,
+      metadata: {
+        ...context.metadata,
+        pluginId: registration.pluginId,
+        hookName: registration.descriptor.name
+      }
+    };
+  }
+}
+function matchesHookDescriptor(descriptor, payload) {
+  const matcher = descriptor.when;
+  if (!matcher)
+    return true;
+  if (matcher.toolName && !matchesValue(matcher.toolName, readToolName(payload)))
+    return false;
+  if (matcher.notificationType && !matchesValue(matcher.notificationType, readNotificationType(payload)))
+    return false;
+  if (matcher.stopReason && !matchesValue(matcher.stopReason, readStopReason(payload)))
+    return false;
+  if (matcher.source && !matchesValue(matcher.source, readSource(payload)))
+    return false;
+  return true;
+}
+function readToolName(payload) {
+  if ("toolCall" in payload)
+    return payload.toolCall.function.name;
+  return;
+}
+function readNotificationType(payload) {
+  if ("notification" in payload)
+    return payload.notification.type;
+  return;
+}
+function readStopReason(payload) {
+  if ("stopReason" in payload)
+    return payload.stopReason;
+  return;
+}
+function readSource(payload) {
+  if ("notification" in payload)
+    return payload.notification.source;
+  return;
+}
+function matchesValue(expected, actual) {
+  if (!actual)
+    return false;
+  if (Array.isArray(expected))
+    return expected.includes(actual);
+  return expected === actual;
+}
+async function withTimeout(promise, timeoutMs, createError) {
+  if (!timeoutMs || timeoutMs <= 0)
+    return await promise;
+  let timeoutHandle;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => reject(createError()), timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timeoutHandle)
+      clearTimeout(timeoutHandle);
+  }
 }
 
 // src/plugin-host/PluginHost.ts
@@ -261,6 +463,7 @@ class PluginHost {
   contextContributors = [];
   promptContributors = [];
   tools = [];
+  sessionControllerFactories = [];
   services;
   cwd;
   agentId;
@@ -278,7 +481,7 @@ class PluginHost {
         manifest: plugin.manifest,
         services: scopedServices
       });
-      this.pipeline.register(plugin.manifest.id, priority, setup?.hooks);
+      this.pipeline.register(plugin.manifest.id, priority, setup?.hooks, scopedServices);
       for (const tool of setup?.tools ?? []) {
         this.tools.push({
           pluginId: plugin.manifest.id,
@@ -289,6 +492,13 @@ class PluginHost {
         this.contextContributors.push({ pluginId: plugin.manifest.id, contributor });
       for (const contributor of setup?.promptContributors ?? [])
         this.promptContributors.push({ pluginId: plugin.manifest.id, contributor });
+      if (setup?.createSessionController) {
+        this.sessionControllerFactories.push({
+          pluginId: plugin.manifest.id,
+          factory: setup.createSessionController,
+          services: scopedServices
+        });
+      }
     }
   }
   pluginTools() {
@@ -297,9 +507,32 @@ class PluginHost {
   recentFiles(limit = 5) {
     return this.tracker?.recentFiles(limit) ?? [];
   }
+  createSessionControllers(input) {
+    const controllers = new Map;
+    for (const entry of this.sessionControllerFactories) {
+      controllers.set(entry.pluginId, entry.factory({
+        sessionId: input.sessionId,
+        metadata: input.metadata ? structuredClone(input.metadata) : undefined,
+        getStatus: input.getStatus,
+        pluginState: entry.services.pluginState,
+        save: input.save,
+        isRunning: input.isRunning
+      }));
+    }
+    return controllers;
+  }
   async runMiddleware(name, payload, context = {}) {
     return this.pipeline.runMiddleware(name, payload, this.createRuntimeContext(context));
   }
+  async runToolBeforeExecute(payload, context = {}) {
+    return this.pipeline.runToolBeforeExecute(payload, this.createRuntimeContext(context));
+  }
+  async runNotifyMessage(payload, context = {}) {
+    return this.pipeline.runNotifyMessage(payload, this.createRuntimeContext(context));
+  }
+  async runRunStop(payload, context = {}) {
+    return this.pipeline.runRunStop(payload, this.createRuntimeContext(context));
+  }
   async runObservers(name, payload, context = {}) {
     await this.pipeline.runObservers(name, payload, this.createRuntimeContext(context));
   }
@@ -332,6 +565,7 @@ class PluginHost {
       sessionId: context.sessionId,
       requestId: context.requestId,
       iteration: context.iteration,
+      status: context.status ? structuredClone(context.status) : undefined,
       metadata: context.metadata,
       services: context.services ?? this.services
     };
@@ -347,6 +581,10 @@ function wrapTool(pluginId, tool, services) {
           ...context.metadata,
           pluginId
         },
+        emitEvent: (event) => context.emitEvent?.({
+          ...event,
+          pluginId: event.pluginId ?? pluginId
+        }),
         services
       });
     }
@@ -678,14 +916,17 @@ function canWriteFs(permissions) {
 // src/services/PermissionGateway.ts
 class PermissionGateway {
   permissions;
+  compactionOwnerPluginId;
   constructor(options = {}) {
     this.permissions = normalizePermissions(options.permissions);
+    this.compactionOwnerPluginId = options.compactionOwnerPluginId;
   }
   get agentPermissions() {
     return { ...this.permissions };
   }
   scopeServices(services, pluginId, requested) {
     const effective = intersectPermissions(this.permissions, requested);
+    const pluginState = services.pluginState;
     return {
       fileSystem: {
         readText: (path3, options) => {
@@ -751,9 +992,33 @@ class PermissionGateway {
             throw new PermissionDeniedError(`Plugin ${pluginId} is not allowed to call the model gateway`);
           return services.model.stream(request);
         }
+      },
+      compaction: {
+        getState: (sessionId) => services.compaction.getState(sessionId),
+        apply: (update) => {
+          this.ensureCompactionOwner(pluginId);
+          return services.compaction.apply(update);
+        },
+        clear: (sessionId) => {
+          this.ensureCompactionOwner(pluginId);
+          return services.compaction.clear(sessionId);
+        }
+      },
+      pluginState: {
+        get: (sessionId) => pluginState.getForPlugin(sessionId, pluginId),
+        replace: (sessionId, entry) => pluginState.replaceForPlugin(sessionId, pluginId, entry),
+        clear: (sessionId) => pluginState.clearForPlugin(sessionId, pluginId)
       }
     };
   }
+  ensureCompactionOwner(pluginId) {
+    if (this.compactionOwnerPluginId === pluginId)
+      return;
+    const message = this.compactionOwnerPluginId ? `Plugin ${pluginId} is not the configured compaction owner (${this.compactionOwnerPluginId})` : `Plugin ${pluginId} cannot modify canonical compaction without compaction.ownerPluginId`;
+    const error = new Error(message);
+    error.code = "compaction_owner_required";
+    throw error;
+  }
 }
 function intersectPermissions(agent, requested) {
   const normalized = requested ?? {};
@@ -1070,6 +1335,294 @@ class WriteTool extends BaseTool {
     });
   }
 }
+// src/agent-core/approvals.ts
+class DefaultApprovalManager {
+  handler;
+  notifications;
+  constructor(options = {}) {
+    this.handler = options.handler;
+    this.notifications = options.notifications;
+  }
+  async requestApproval(request, context) {
+    const normalizedRequest = {
+      ...request,
+      id: request.id ?? createId("approval")
+    };
+    await this.notifications?.emit({
+      type: "approval.requested",
+      source: "approval",
+      level: "warning",
+      message: normalizedRequest.message,
+      metadata: {
+        approvalId: normalizedRequest.id,
+        toolName: normalizedRequest.toolCall.function.name
+      }
+    }, context);
+    if (!this.handler) {
+      const denied = {
+        type: "denied",
+        reason: "No approval handler configured"
+      };
+      await this.notifications?.emit({
+        type: "approval.denied",
+        source: "approval",
+        level: "warning",
+        message: denied.reason,
+        metadata: {
+          approvalId: normalizedRequest.id,
+          toolName: normalizedRequest.toolCall.function.name
+        }
+      }, context);
+      return denied;
+    }
+    const decision = await this.handler(normalizedRequest);
+    await this.notifications?.emit({
+      type: decision.type === "approved" ? "approval.approved" : "approval.denied",
+      source: "approval",
+      level: decision.type === "approved" ? "info" : "warning",
+      message: decision.type === "approved" ? `Approved tool call: ${normalizedRequest.toolCall.function.name}` : decision.reason ?? `Denied tool call: ${normalizedRequest.toolCall.function.name}`,
+      metadata: {
+        approvalId: normalizedRequest.id,
+        toolName: normalizedRequest.toolCall.function.name
+      }
+    }, context);
+    return decision;
+  }
+}
+
+// src/agent-core/session-state.ts
+function touchRuntimeSessionState(state) {
+  state.updatedAt = Date.now();
+}
+
+// src/agent-core/compaction.ts
+function createEmptyCompactionState() {
+  return {
+    cursor: 0,
+    systemSegments: [],
+    checkpoints: []
+  };
+}
+function cloneCompactionState(state) {
+  if (!state)
+    return createEmptyCompactionState();
+  return structuredClone({
+    cursor: state.cursor,
+    systemSegments: [...state.systemSegments],
+    checkpoints: state.checkpoints.map((checkpoint) => ({
+      ...checkpoint,
+      systemSegments: [...checkpoint.systemSegments],
+      metadata: checkpoint.metadata ? structuredClone(checkpoint.metadata) : undefined
+    }))
+  });
+}
+function normalizeCompactionState(state, messages) {
+  const current = cloneCompactionState(state);
+  return {
+    cursor: clampCursor(current.cursor, messages.length),
+    systemSegments: current.systemSegments.filter(Boolean),
+    checkpoints: current.checkpoints.map((checkpoint) => ({
+      ...checkpoint,
+      cursor: clampCursor(checkpoint.cursor, messages.length),
+      systemSegments: checkpoint.systemSegments.filter(Boolean)
+    }))
+  };
+}
+function applyCompactionUpdate(state, update) {
+  const nextCursor = clampCursor(update.cursor, state.messages.length);
+  const nextSystemSegments = [...update.systemSegments ?? state.compaction.systemSegments].filter(Boolean);
+  const nextCheckpoint = {
+    id: createId("compact"),
+    cursor: nextCursor,
+    systemSegments: nextSystemSegments,
+    summary: update.summary,
+    reason: update.reason ?? "manual",
+    createdAt: Date.now(),
+    metadata: update.metadata ? structuredClone(update.metadata) : undefined
+  };
+  state.compaction = {
+    cursor: nextCursor,
+    systemSegments: nextSystemSegments,
+    checkpoints: [...state.compaction.checkpoints, nextCheckpoint]
+  };
+  touchRuntimeSessionState(state);
+  return cloneCompactionState(state.compaction);
+}
+function clearCompactionState(state) {
+  state.compaction = createEmptyCompactionState();
+  touchRuntimeSessionState(state);
+  return cloneCompactionState(state.compaction);
+}
+function projectMessagesForRequest(messages, compaction) {
+  const leadingSystemMessages = readLeadingSystemMessages(messages);
+  const startIndex = Math.max(compaction.cursor, leadingSystemMessages.length);
+  return [
+    ...leadingSystemMessages,
+    ...messages.slice(startIndex)
+  ];
+}
+function buildCompactionPromptSegments(compaction) {
+  return compaction.systemSegments.filter(Boolean);
+}
+function calculateThresholdTokens(options) {
+  if (options.triggerTokens !== undefined)
+    return options.triggerTokens;
+  const ratio = options.triggerRatio ?? 0.8;
+  return Math.max(1, Math.floor(options.maxInputTokens * ratio));
+}
+async function estimateCompactionBudget(options, input) {
+  const estimatedInputTokens = options.estimator ? await options.estimator(input) : estimateByHeuristic(input);
+  return {
+    estimatedInputTokens,
+    thresholdTokens: calculateThresholdTokens(options),
+    maxInputTokens: options.maxInputTokens
+  };
+}
+function isCompactionRequired(options, budget) {
+  if (!options || options.enabled === false || !budget)
+    return false;
+  return budget.estimatedInputTokens >= budget.thresholdTokens;
+}
+function didCompactionStateChange(before, after) {
+  return before.cursor !== after.cursor || JSON.stringify(before.systemSegments) !== JSON.stringify(after.systemSegments) || before.checkpoints.length !== after.checkpoints.length;
+}
+
+class DefaultCompactionService {
+  sessions = new Map;
+  registerSession(state) {
+    state.compaction = normalizeCompactionState(state.compaction, state.messages);
+    this.sessions.set(state.id, state);
+  }
+  unregisterSession(sessionId) {
+    this.sessions.delete(sessionId);
+  }
+  async getState(sessionId) {
+    return cloneCompactionState(this.requireSession(sessionId).compaction);
+  }
+  async apply(update) {
+    return applyCompactionUpdate(this.requireSession(update.sessionId), update);
+  }
+  async clear(sessionId) {
+    return clearCompactionState(this.requireSession(sessionId));
+  }
+  requireSession(sessionId) {
+    const state = this.sessions.get(sessionId);
+    if (!state)
+      throw new Error(`Unknown session for compaction: ${sessionId}`);
+    return state;
+  }
+}
+function clampCursor(cursor, max) {
+  if (!Number.isFinite(cursor))
+    return 0;
+  return Math.max(0, Math.min(Math.floor(cursor), max));
+}
+function readLeadingSystemMessages(messages) {
+  const systemMessages = [];
+  for (const message of messages) {
+    if (message.role !== "system")
+      break;
+    systemMessages.push(message);
+  }
+  return systemMessages;
+}
+function estimateByHeuristic(input) {
+  const messageChars = input.messages.reduce((total, message) => {
+    const contentChars = JSON.stringify(message.content).length;
+    const metadataChars = message.metadata ? JSON.stringify(message.metadata).length : 0;
+    return total + message.role.length + contentChars + metadataChars;
+  }, 0);
+  const toolChars = input.tools ? JSON.stringify(input.tools).length : 0;
+  const modelChars = `${input.model.provider}:${input.model.modelId}`.length;
+  return Math.max(1, Math.ceil((messageChars + toolChars + modelChars) / 4));
+}
+
+// src/agent-core/plugin-state.ts
+var APP_PLUGIN_NAMESPACE = "__agent__";
+function clonePluginSessionStateEntry(entry) {
+  if (!entry)
+    return null;
+  return structuredClone({
+    version: entry.version,
+    data: structuredClone(entry.data),
+    updatedAt: entry.updatedAt
+  });
+}
+function clonePluginStateMap(state) {
+  if (!state)
+    return {};
+  return Object.fromEntries(Object.entries(state).map(([pluginId, entry]) => [pluginId, clonePluginSessionStateEntry(entry)]));
+}
+function normalizePluginStateMap(state) {
+  if (!state)
+    return {};
+  return Object.fromEntries(Object.entries(state).map(([pluginId, entry]) => [pluginId, normalizePluginSessionStateEntry(entry, `Plugin session state for ${pluginId}`)]));
+}
+
+class DefaultPluginStateService {
+  sessions = new Map;
+  registerSession(state) {
+    state.pluginState = normalizePluginStateMap(state.pluginState);
+    this.sessions.set(state.id, state);
+  }
+  unregisterSession(sessionId) {
+    this.sessions.delete(sessionId);
+  }
+  async get(sessionId) {
+    return this.getForPlugin(sessionId, APP_PLUGIN_NAMESPACE);
+  }
+  async replace(sessionId, entry) {
+    return this.replaceForPlugin(sessionId, APP_PLUGIN_NAMESPACE, entry);
+  }
+  async clear(sessionId) {
+    await this.clearForPlugin(sessionId, APP_PLUGIN_NAMESPACE);
+  }
+  async getForPlugin(sessionId, pluginId) {
+    const state = this.requireSession(sessionId);
+    return clonePluginSessionStateEntry(state.pluginState[pluginId]);
+  }
+  async replaceForPlugin(sessionId, pluginId, entry) {
+    const state = this.requireSession(sessionId);
+    const nextEntry = normalizePluginSessionStateEntry(entry, `Plugin session state for ${pluginId}`);
+    state.pluginState = {
+      ...state.pluginState,
+      [pluginId]: nextEntry
+    };
+    touchRuntimeSessionState(state);
+    return clonePluginSessionStateEntry(nextEntry);
+  }
+  async clearForPlugin(sessionId, pluginId) {
+    const state = this.requireSession(sessionId);
+    if (!(pluginId in state.pluginState))
+      return;
+    const nextState = { ...state.pluginState };
+    delete nextState[pluginId];
+    state.pluginState = nextState;
+    touchRuntimeSessionState(state);
+  }
+  async list(sessionId) {
+    return clonePluginStateMap(this.requireSession(sessionId).pluginState);
+  }
+  requireSession(sessionId) {
+    const state = this.sessions.get(sessionId);
+    if (!state)
+      throw new Error(`Unknown session for plugin state: ${sessionId}`);
+    return state;
+  }
+}
+function normalizePluginSessionStateEntry(entry, label) {
+  if (!Number.isFinite(entry.version))
+    throw new TypeError(`${label} version must be a finite number`);
+  if (!Number.isFinite(entry.updatedAt))
+    throw new TypeError(`${label} updatedAt must be a finite number`);
+  assertJsonSafeObject(entry.data, `${label} data`);
+  return {
+    version: Math.floor(entry.version),
+    data: structuredClone(entry.data),
+    updatedAt: entry.updatedAt
+  };
+}
+
 // src/agent-core/MessageFactory.ts
 class DefaultMessageFactory {
   createSystemMessage(input) {
@@ -1114,6 +1667,46 @@ class DefaultMessageFactory {
   }
 }
 
+// src/agent-core/notifications.ts
+class DefaultNotificationBus {
+  pluginHost;
+  services;
+  constructor(options) {
+    this.pluginHost = options.pluginHost;
+    this.services = options.services;
+  }
+  async emit(notification, context = {}) {
+    const normalized = {
+      id: notification.id ?? createId("note"),
+      level: notification.level ?? "info",
+      ...notification
+    };
+    if (!this.pluginHost)
+      return normalized;
+    const result = await this.pluginHost.runNotifyMessage({ notification: normalized }, {
+      sessionId: context.sessionId,
+      requestId: context.requestId,
+      iteration: context.iteration,
+      cwd: context.cwd,
+      status: context.status,
+      metadata: context.metadata,
+      services: this.services
+    });
+    if (result.suppressed)
+      return;
+    await this.pluginHost.runObservers("notify.message", result.payload, {
+      sessionId: context.sessionId,
+      requestId: context.requestId,
+      iteration: context.iteration,
+      cwd: context.cwd,
+      status: context.status,
+      metadata: context.metadata,
+      services: this.services
+    });
+    return result.payload.notification;
+  }
+}
+
 // src/persistence/SnapshotCodec.ts
 class JsonSnapshotCodec {
   encode(input) {
@@ -1124,6 +1717,8 @@ class JsonSnapshotCodec {
       cwd: input.cwd,
       messages: input.messages,
       usage: input.usage,
+      compaction: input.compaction,
+      pluginState: input.pluginState,
       createdAt: input.createdAt,
       updatedAt: input.updatedAt,
       metadata: input.metadata
@@ -1199,10 +1794,19 @@ function finalizeToolCall(draft) {
 // src/agent-core/errors.ts
 class SessionExecutionError extends Error {
   payload;
+  payloadSummary;
   constructor(payload) {
     super(payload.message);
     this.name = "SessionExecutionError";
     this.payload = payload;
+    this.payloadSummary = stringifyPayload(payload);
+  }
+}
+function stringifyPayload(payload) {
+  try {
+    return JSON.stringify(payload, null, 2);
+  } catch {
+    return String(payload);
   }
 }
 
@@ -1297,9 +1901,19 @@ class DefaultModelTurnCollector {
   }
 }
 
-// src/agent-core/session-state.ts
-function touchRuntimeSessionState(state) {
-  state.updatedAt = Date.now();
+// src/agent-core/session-status.ts
+function createSessionStatus(state) {
+  return {
+    sessionId: state.id,
+    model: { ...state.modelRef },
+    cwd: state.cwd,
+    usage: { ...state.usage },
+    compaction: cloneCompactionState(state.compaction),
+    messageCount: state.messages.length,
+    createdAt: state.createdAt,
+    updatedAt: state.updatedAt,
+    metadata: state.metadata ? structuredClone(state.metadata) : undefined
+  };
 }
 
 // src/agent-core/LoopRunner.ts
@@ -1310,6 +1924,7 @@ class LoopRunner {
   terminationPolicy;
   contextManager;
   pluginHost;
+  notificationBus;
   constructor(dependencies) {
     this.messageFactory = dependencies.messageFactory;
     this.turnCollector = dependencies.turnCollector;
@@ -1317,36 +1932,44 @@ class LoopRunner {
     this.terminationPolicy = dependencies.terminationPolicy;
     this.contextManager = dependencies.contextManager;
     this.pluginHost = dependencies.pluginHost;
+    this.notificationBus = dependencies.notificationBus;
   }
   async* run(state, input, options = {}) {
-    const startPayload = await this.pluginHost?.runMiddleware("session.start", {
+    const startPayload = await this.pluginHost?.runMiddleware("run.start", {
       sessionId: state.id,
       input
-    }, {
-      sessionId: state.id,
-      cwd: state.cwd,
-      metadata: state.metadata
-    });
+    }, this.createHookContext(state));
     const initialInput = startPayload?.input ?? input;
+    await this.pluginHost?.runObservers("run.start", {
+      sessionId: state.id,
+      input: initialInput
+    }, this.createHookContext(state));
     const userMessage = this.messageFactory.createUserMessage(initialInput);
     state.messages.push(userMessage);
     touchRuntimeSessionState(state);
+    await this.notificationBus.emit({
+      type: "run.start",
+      source: "runtime",
+      message: `Run started for session ${state.id}`,
+      metadata: {
+        sessionId: state.id
+      }
+    }, {
+      ...this.createHookContext(state)
+    });
     let lastRequestId;
+    let lastIteration = 0;
+    let pendingContextSegments = [];
     try {
       for (let iteration = 0;iteration < state.maxIterations; iteration += 1) {
+        lastIteration = iteration;
         const requestId = createId("req");
         lastRequestId = requestId;
         const turnStart = await this.pluginHost?.runMiddleware("turn.start", {
           requestId,
           iteration,
           messages: [...state.messages]
-        }, {
-          sessionId: state.id,
-          requestId,
-          iteration,
-          cwd: state.cwd,
-          metadata: state.metadata
-        });
+        }, this.createHookContext(state, { requestId, iteration }));
         const contextItems = await this.contextManager.resolve({
           sessionId: state.id,
           input: initialInput,
@@ -1357,13 +1980,7 @@ class LoopRunner {
           contextItems,
           input: initialInput,
           messages: [...state.messages]
-        }, {
-          sessionId: state.id,
-          requestId,
-          iteration,
-          cwd: state.cwd,
-          metadata: state.metadata
-        });
+        }, this.createHookContext(state, { requestId, iteration }));
         const effectiveContext = resolvedContext?.contextItems ?? contextItems;
         const pluginPromptSegments = await this.pluginHost?.collectPromptSegments({
           sessionId: state.id,
@@ -1373,37 +1990,31 @@ class LoopRunner {
           cwd: state.cwd
         }) ?? [];
         const promptSegments = [
+          ...pendingContextSegments,
           ...this.contextManager.format(effectiveContext),
           ...pluginPromptSegments
         ];
+        pendingContextSegments = [];
         const resolvedPrompt = await this.pluginHost?.runMiddleware("prompt.resolve", {
           promptSegments,
           contextItems: effectiveContext,
           messages: [...state.messages]
-        }, {
-          sessionId: state.id,
-          requestId,
-          iteration,
-          cwd: state.cwd,
-          metadata: state.metadata
-        });
+        }, this.createHookContext(state, { requestId, iteration }));
         const effectivePromptSegments = resolvedPrompt?.promptSegments ?? promptSegments;
         const toolDefinitions = state.tools?.definitions() ?? [];
         const resolvedToolset = await this.pluginHost?.runMiddleware("toolset.resolve", {
           tools: toolDefinitions
-        }, {
-          sessionId: state.id,
+        }, this.createHookContext(state, { requestId, iteration }));
+        const effectiveTools = resolvedToolset?.tools ?? toolDefinitions;
+        const requestMessages = await this.resolveRequestMessages({
+          state,
           requestId,
           iteration,
-          cwd: state.cwd,
-          metadata: state.metadata
+          baseMessages: [...turnStart?.messages ?? state.messages],
+          runtimePromptSegments: effectivePromptSegments,
+          contextItems: effectiveContext,
+          tools: effectiveTools
         });
-        const effectiveTools = resolvedToolset?.tools ?? toolDefinitions;
-        const requestMessages = [...turnStart?.messages ?? state.messages];
-        if (effectivePromptSegments.length > 0)
-          requestMessages.unshift(this.messageFactory.createSystemMessage(effectivePromptSegments.join(`
-
-`)));
         const request = {
           requestId,
           model: state.modelRef,
@@ -1414,25 +2025,30 @@ class LoopRunner {
         };
         const resolvedRequest = await this.pluginHost?.runMiddleware("model.request", {
           request
-        }, {
-          sessionId: state.id,
-          requestId,
-          iteration,
-          cwd: state.cwd,
-          metadata: state.metadata
-        });
+        }, this.createHookContext(state, { requestId, iteration }));
         const effectiveRequest = resolvedRequest?.request ?? request;
         const turn = yield* this.turnCollector.collect({
           sessionId: state.id,
           requestId,
           events: state.model.stream(effectiveRequest),
           onEvent: async (event) => {
+            if (event.type === "error") {
+              await this.notificationBus.emit({
+                type: "provider.error",
+                source: "provider",
+                level: "error",
+                message: event.error.message,
+                metadata: {
+                  requestId,
+                  code: event.error.code,
+                  status: event.error.status
+                }
+              }, {
+                ...this.createHookContext(state, { requestId, iteration })
+              });
+            }
             await this.pluginHost?.runObservers("model.event", { event }, {
-              sessionId: state.id,
-              requestId,
-              iteration,
-              cwd: state.cwd,
-              metadata: state.metadata
+              ...this.createHookContext(state, { requestId, iteration })
             });
           }
         });
@@ -1445,53 +2061,85 @@ class LoopRunner {
         });
         const assistantPayload = await this.pluginHost?.runMiddleware("assistant.message", {
           message: assistantDraft
-        }, {
-          sessionId: state.id,
-          requestId,
-          iteration,
-          cwd: state.cwd,
-          metadata: state.metadata
-        });
-        const assistantMessage = assistantPayload?.message ?? assistantDraft;
+        }, this.createHookContext(state, { requestId, iteration }));
+        let assistantMessage = assistantPayload?.message ?? assistantDraft;
         state.messages.push(assistantMessage);
         state.usage = addUsage(state.usage, turn.usage);
         touchRuntimeSessionState(state);
         const baseDecision = this.terminationPolicy.afterAssistantTurn(turn.toolCalls);
-        const decisionPayload = await this.pluginHost?.runMiddleware("loop.decide", {
+        const stopBasePayload = {
+          assistantMessage,
           toolCalls: turn.toolCalls,
           stopReason: turn.stopReason,
           decision: baseDecision
-        }, {
-          sessionId: state.id,
-          requestId,
-          iteration,
-          cwd: state.cwd,
-          metadata: state.metadata
+        };
+        const stopResult = await this.pluginHost?.runRunStop(stopBasePayload, {
+          ...this.createHookContext(state, { requestId, iteration })
         });
-        const decision = decisionPayload?.decision ?? baseDecision;
-        if (decision.type === "done") {
+        const stopPayload = stopResult?.payload ?? stopBasePayload;
+        const stopControl = stopResult?.control;
+        await this.pluginHost?.runObservers("run.stop", {
+          ...stopPayload,
+          additionalContext: stopControl?.type === "finalize" ? stopControl.additionalContext ?? stopPayload.additionalContext : stopPayload.additionalContext,
+          finalMessage: stopControl?.type === "finalize" ? stopControl.finalMessage ?? stopPayload.finalMessage : stopPayload.finalMessage
+        }, this.createHookContext(state, { requestId, iteration }));
+        const stopDecision = stopControl?.type === "finalize" ? { type: "done" } : stopPayload.decision;
+        const additionalContext = stopControl?.type === "finalize" ? stopControl.additionalContext : stopPayload.additionalContext;
+        const finalMessage = stopControl?.type === "finalize" ? stopControl.finalMessage ?? stopPayload.finalMessage ?? stopPayload.assistantMessage : stopPayload.finalMessage ?? stopPayload.assistantMessage;
+        if (additionalContext && additionalContext.length > 0 && stopDecision.type === "continue")
+          pendingContextSegments = [...pendingContextSegments, ...additionalContext];
+        if (stopDecision.type === "done") {
+          assistantMessage = finalMessage;
+          state.messages[state.messages.length - 1] = assistantMessage;
+          touchRuntimeSessionState(state);
+          const endPayload = await this.pluginHost?.runMiddleware("run.end", {
+            message: assistantMessage,
+            usage: { ...state.usage }
+          }, this.createHookContext(state, { requestId, iteration }));
+          const completedMessage = endPayload?.message ?? assistantMessage;
+          const completedUsage = endPayload?.usage ?? { ...state.usage };
+          state.messages[state.messages.length - 1] = completedMessage;
+          state.usage = { ...completedUsage };
+          touchRuntimeSessionState(state);
+          await this.notificationBus.emit({
+            type: "run.end",
+            source: "runtime",
+            message: `Run completed for session ${state.id}`,
+            metadata: {
+              sessionId: state.id,
+              requestId
+            }
+          }, {
+            ...this.createHookContext(state, { requestId, iteration })
+          });
           yield {
             type: "done",
             sessionId: state.id,
-            message: assistantMessage,
-            usage: { ...state.usage }
+            message: completedMessage,
+            usage: completedUsage
           };
-          await this.pluginHost?.runObservers("session.end", { message: assistantMessage }, {
-            sessionId: state.id,
-            requestId,
-            iteration,
-            cwd: state.cwd,
-            metadata: state.metadata
-          });
-          await options.onDone?.(assistantMessage);
-          return assistantMessage;
+          await this.pluginHost?.runObservers("run.end", {
+            message: completedMessage,
+            usage: completedUsage
+          }, this.createHookContext(state, { requestId, iteration }));
+          await options.onDone?.(completedMessage);
+          return completedMessage;
         }
         for (const toolCall of turn.toolCalls) {
           yield { type: "tool_call", sessionId: state.id, toolCall };
+          const pluginEvents = [];
           const result = await this.toolExecutor.execute(toolCall, {
             signal: options.signal,
-            cwd: state.cwd
+            cwd: state.cwd,
+            requestId,
+            iteration,
+            status: createSessionStatus(state),
+            onEvent: async (event) => {
+              pluginEvents.push(event);
+            }
           });
+          for (const event of pluginEvents)
+            yield event;
           const toolMessage = this.messageFactory.createToolMessage(toolCall, result);
           state.messages.push(toolMessage);
           touchRuntimeSessionState(state);
@@ -1500,25 +2148,151 @@ class LoopRunner {
       }
     } catch (error) {
       if (error instanceof SessionExecutionError) {
+        await this.notificationBus.emit({
+          type: error.payload.code.startsWith("openai_") || error.payload.code.startsWith("anthropic_") || error.payload.code.startsWith("gemini_") ? "provider.error" : "runtime.error",
+          source: error.payload.code.includes("_http_") || error.payload.code.includes("_request_") ? "provider" : "runtime",
+          level: "error",
+          message: error.payload.message,
+          metadata: {
+            requestId: lastRequestId,
+            code: error.payload.code
+          }
+        }, {
+          ...this.createHookContext(state, { requestId: lastRequestId, iteration: lastIteration })
+        });
         await this.pluginHost?.runObservers("session.error", { error: error.payload }, {
-          sessionId: state.id,
-          requestId: lastRequestId,
-          cwd: state.cwd,
-          metadata: state.metadata
+          ...this.createHookContext(state, { requestId: lastRequestId })
         });
       }
       throw error;
     }
     const payload = this.terminationPolicy.onMaxIterationsExceeded(state.maxIterations, lastRequestId);
     yield { type: "error", sessionId: state.id, error: payload };
+    await this.notificationBus.emit({
+      type: "runtime.error",
+      source: "runtime",
+      level: "error",
+      message: payload.message,
+      metadata: {
+        requestId: lastRequestId,
+        code: payload.code
+      }
+    }, {
+      ...this.createHookContext(state, { requestId: lastRequestId, iteration: lastIteration })
+    });
     await this.pluginHost?.runObservers("session.error", { error: payload }, {
-      sessionId: state.id,
-      requestId: lastRequestId,
-      cwd: state.cwd,
-      metadata: state.metadata
+      ...this.createHookContext(state, { requestId: lastRequestId })
     });
     throw new SessionExecutionError(payload);
   }
+  async resolveRequestMessages(input) {
+    const initialAttempt = await this.buildProjectedRequestMessages(input.state, input.baseMessages, input.runtimePromptSegments, input.tools);
+    if (!isCompactionRequired(input.state.compactionOptions, initialAttempt.budget))
+      return initialAttempt.messages;
+    const budget = initialAttempt.budget;
+    if (!budget)
+      return initialAttempt.messages;
+    await this.notificationBus.emit({
+      type: "context.compaction.required",
+      source: "runtime",
+      level: "warning",
+      message: `Context compaction required for session ${input.state.id}`,
+      metadata: {
+        requestId: input.requestId,
+        estimatedInputTokens: budget.estimatedInputTokens,
+        thresholdTokens: budget.thresholdTokens,
+        maxInputTokens: budget.maxInputTokens,
+        cursor: input.state.compaction.cursor
+      }
+    }, {
+      ...this.createHookContext(input.state, { requestId: input.requestId, iteration: input.iteration })
+    });
+    const beforeState = cloneCompactionState(input.state.compaction);
+    const compactPayload = await this.pluginHost?.runMiddleware("context.compact.before", {
+      sessionId: input.state.id,
+      messages: [...input.state.messages],
+      cursor: beforeState.cursor,
+      systemSegments: [...beforeState.systemSegments],
+      contextItems: input.contextItems,
+      estimatedInputTokens: budget.estimatedInputTokens,
+      thresholdTokens: budget.thresholdTokens,
+      maxInputTokens: budget.maxInputTokens,
+      trigger: "threshold"
+    }, {
+      ...this.createHookContext(input.state, { requestId: input.requestId, iteration: input.iteration })
+    });
+    await this.pluginHost?.runObservers("context.compact.before", compactPayload ?? {
+      sessionId: input.state.id,
+      messages: [...input.state.messages],
+      cursor: beforeState.cursor,
+      systemSegments: [...beforeState.systemSegments],
+      contextItems: input.contextItems,
+      estimatedInputTokens: budget.estimatedInputTokens,
+      thresholdTokens: budget.thresholdTokens,
+      maxInputTokens: budget.maxInputTokens,
+      trigger: "threshold"
+    }, {
+      ...this.createHookContext(input.state, { requestId: input.requestId, iteration: input.iteration })
+    });
+    input.state.compaction = normalizeCompactionState(input.state.compaction, input.state.messages);
+    const afterState = cloneCompactionState(input.state.compaction);
+    if (didCompactionStateChange(beforeState, afterState)) {
+      const latestCheckpoint = afterState.checkpoints.at(-1);
+      await this.notificationBus.emit({
+        type: "context.compacted",
+        source: "runtime",
+        level: "info",
+        message: `Context compacted for session ${input.state.id}`,
+        metadata: {
+          requestId: input.requestId,
+          cursor: afterState.cursor,
+          checkpointId: latestCheckpoint?.id,
+          reason: latestCheckpoint?.reason
+        }
+      }, {
+        ...this.createHookContext(input.state, { requestId: input.requestId, iteration: input.iteration })
+      });
+    }
+    const compactedAttempt = await this.buildProjectedRequestMessages(input.state, input.baseMessages, input.runtimePromptSegments, input.tools);
+    if (!isCompactionRequired(input.state.compactionOptions, compactedAttempt.budget))
+      return compactedAttempt.messages;
+    throw new SessionExecutionError({
+      code: "context_compaction_required",
+      message: `Context compaction required before continuing the run (estimated ${budget.estimatedInputTokens} tokens, threshold ${budget.thresholdTokens})`,
+      requestId: input.requestId
+    });
+  }
+  async buildProjectedRequestMessages(state, baseMessages, runtimePromptSegments, tools) {
+    const projectedMessages = projectMessagesForRequest(baseMessages, state.compaction);
+    const promptSegments = [
+      ...buildCompactionPromptSegments(state.compaction),
+      ...runtimePromptSegments
+    ];
+    const requestMessages = [...projectedMessages];
+    if (promptSegments.length > 0)
+      requestMessages.unshift(this.messageFactory.createSystemMessage(promptSegments.join(`
+
+`)));
+    const budget = state.compactionOptions && state.compactionOptions.enabled !== false ? await estimateCompactionBudget(state.compactionOptions, {
+      model: state.modelRef,
+      messages: requestMessages,
+      tools
+    }) : undefined;
+    return {
+      messages: requestMessages,
+      budget
+    };
+  }
+  createHookContext(state, input = {}) {
+    return {
+      sessionId: state.id,
+      requestId: input.requestId,
+      iteration: input.iteration,
+      cwd: state.cwd,
+      metadata: state.metadata,
+      status: createSessionStatus(state)
+    };
+  }
 }
 
 // src/agent-core/TerminationPolicy.ts
@@ -1542,52 +2316,117 @@ class DefaultToolExecutor {
   metadata;
   services;
   pluginHost;
+  approvalManager;
+  notificationBus;
   constructor(options) {
     this.sessionId = options.sessionId;
     this.tools = options.tools;
     this.metadata = options.metadata;
     this.services = options.services;
     this.pluginHost = options.pluginHost;
+    this.approvalManager = options.approvalManager;
+    this.notificationBus = options.notificationBus;
   }
   async execute(toolCall, options = {}) {
-    const before = await this.pluginHost?.runMiddleware("tool.beforeExecute", {
-      toolCall
-    }, {
+    const hookContext = {
       sessionId: this.sessionId,
+      requestId: options.requestId,
+      iteration: options.iteration,
       cwd: options.cwd,
+      status: options.status,
       services: this.services,
       metadata: this.metadata
-    });
-    const currentToolCall = before?.toolCall ?? toolCall;
-    const tool = this.tools?.get(currentToolCall.function.name);
-    if (!tool)
-      return normalizeToolResult({ ...textToolResult(`Tool not found: ${currentToolCall.function.name}`), isError: true });
+    };
+    const before = await this.pluginHost?.runToolBeforeExecute({
+      toolCall
+    }, hookContext);
+    let currentToolCall = before?.payload.toolCall ?? toolCall;
     let result;
-    try {
-      result = normalizeToolResult(await tool.execute(currentToolCall.function.arguments, {
-        sessionId: this.sessionId,
-        cwd: options.cwd,
-        signal: options.signal,
-        metadata: this.metadata,
-        services: this.services
-      }));
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      result = normalizeToolResult({
-        ...textToolResult(message),
-        isError: true
-      });
+    if (before?.control) {
+      if (before.control.type === "provideResult") {
+        result = normalizeToolResult(before.control.result);
+      } else if (before.control.type === "deny") {
+        result = normalizeToolResult(before.control.result ?? {
+          ...textToolResult(before.control.reason ?? `Tool denied: ${currentToolCall.function.name}`),
+          isError: true
+        });
+        await this.notificationBus.emit({
+          type: "tool.denied",
+          source: "permission",
+          level: "warning",
+          message: before.control.reason ?? `Tool denied: ${currentToolCall.function.name}`,
+          metadata: {
+            toolName: currentToolCall.function.name
+          }
+        }, hookContext);
+      } else if (before.control.type === "ask") {
+        currentToolCall = before.control.toolCall ?? currentToolCall;
+        const approvalRequest = {
+          id: undefined,
+          kind: "tool_execution",
+          toolCall: currentToolCall,
+          message: before.control.request?.message ?? `Approval required to execute tool: ${currentToolCall.function.name}`,
+          metadata: before.control.request?.metadata
+        };
+        const decision = await this.approvalManager.requestApproval(approvalRequest, hookContext);
+        if (decision.type === "denied") {
+          result = normalizeToolResult({
+            ...textToolResult(decision.reason ?? `Tool approval denied: ${currentToolCall.function.name}`),
+            isError: true
+          });
+        }
+      }
+    }
+    if (!result) {
+      const tool = this.tools?.get(currentToolCall.function.name);
+      if (!tool) {
+        result = normalizeToolResult({ ...textToolResult(`Tool not found: ${currentToolCall.function.name}`), isError: true });
+      } else {
+        try {
+          result = normalizeToolResult(await tool.execute(currentToolCall.function.arguments, {
+            sessionId: this.sessionId,
+            cwd: options.cwd,
+            signal: options.signal,
+            metadata: this.metadata,
+            services: this.services,
+            emitEvent: async (event) => {
+              const pluginId = event.pluginId;
+              if (!pluginId)
+                throw new Error(`Tool ${currentToolCall.function.name} emitted a plugin event without pluginId`);
+              await options.onEvent?.({
+                type: "plugin_event",
+                sessionId: this.sessionId,
+                pluginId,
+                event: event.event,
+                data: event.data ? structuredClone(event.data) : undefined
+              });
+            }
+          }));
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          result = normalizeToolResult({
+            ...textToolResult(message),
+            isError: true
+          });
+        }
+      }
     }
     const after = await this.pluginHost?.runMiddleware("tool.afterExecute", {
       toolCall: currentToolCall,
       result
-    }, {
-      sessionId: this.sessionId,
-      cwd: options.cwd,
-      services: this.services,
-      metadata: this.metadata
-    });
-    return normalizeToolResult(after?.result ?? result);
+    }, hookContext);
+    const finalResult = normalizeToolResult(after?.result ?? result);
+    await this.notificationBus.emit({
+      type: finalResult.isError ? "tool.failed" : "tool.completed",
+      source: "tool",
+      level: finalResult.isError ? "error" : "info",
+      message: finalResult.isError ? `Tool failed: ${currentToolCall.function.name}` : `Tool completed: ${currentToolCall.function.name}`,
+      metadata: {
+        toolName: currentToolCall.function.name,
+        isError: finalResult.isError === true
+      }
+    }, hookContext);
+    return finalResult;
   }
 }
 
@@ -1600,6 +2439,12 @@ class Session {
   pluginHost;
   contextManager;
   services;
+  approvalManager;
+  notificationBus;
+  compactionService;
+  pluginStateService;
+  pluginControllers;
+  activeRunCount = 0;
   constructor(options) {
     const now = Date.now();
     this.id = options.id ?? createId("session");
@@ -1608,6 +2453,10 @@ class Session {
     this.pluginHost = options.pluginHost;
     this.contextManager = options.contextManager;
     this.services = options.services;
+    this.approvalManager = options.approvalManager;
+    this.notificationBus = options.notificationBus;
+    this.compactionService = options.compactionService;
+    this.pluginStateService = options.pluginStateService;
     this.state = {
       id: this.id,
       model: options.model,
@@ -1619,9 +2468,21 @@ class Session {
       reasoning: options.reasoning,
       messages: [...options.messages ?? []],
       usage: options.usage ? { ...options.usage } : createEmptyUsage(),
+      compaction: cloneCompactionState(options.compaction ?? createEmptyCompactionState()),
+      pluginState: clonePluginStateMap(options.pluginState),
+      compactionOptions: options.compactionOptions,
       createdAt: this.createdAt,
       updatedAt: options.updatedAt ?? now
     };
+    this.compactionService.registerSession(this.state);
+    this.pluginStateService.registerSession(this.state);
+    this.pluginControllers = this.pluginHost?.createSessionControllers({
+      sessionId: this.id,
+      metadata: this.state.metadata,
+      getStatus: () => this.getStatus(),
+      save: () => this.save(),
+      isRunning: () => this.activeRunCount > 0
+    }) ?? new Map;
   }
   get messages() {
     return [...this.state.messages];
@@ -1629,6 +2490,21 @@ class Session {
   get usage() {
     return { ...this.state.usage };
   }
+  getStatus() {
+    return createSessionStatus(this.state);
+  }
+  getCompactionState() {
+    return cloneCompactionState(this.state.compaction);
+  }
+  getPluginState(pluginId) {
+    return clonePluginSessionStateEntry(this.state.pluginState[pluginId]);
+  }
+  listPluginStates() {
+    return clonePluginStateMap(this.state.pluginState);
+  }
+  getPlugin(pluginId) {
+    return this.pluginControllers.get(pluginId) ?? null;
+  }
   get updatedAt() {
     return this.state.updatedAt;
   }
@@ -1639,20 +2515,76 @@ class Session {
     this.state.cwd = cwd;
     touchRuntimeSessionState(this.state);
   }
+  async compact(update) {
+    const beforeState = this.getCompactionState();
+    const estimatedInputTokens = await this.readEstimatedInputTokens();
+    const thresholdTokens = this.state.compactionOptions?.triggerTokens ?? (this.state.compactionOptions ? Math.max(1, Math.floor(this.state.compactionOptions.maxInputTokens * (this.state.compactionOptions.triggerRatio ?? 0.8))) : 0);
+    const maxInputTokens = this.state.compactionOptions?.maxInputTokens ?? 0;
+    const payload = {
+      sessionId: this.id,
+      messages: this.messages,
+      cursor: beforeState.cursor,
+      systemSegments: [...beforeState.systemSegments],
+      contextItems: undefined,
+      estimatedInputTokens,
+      thresholdTokens,
+      maxInputTokens,
+      trigger: "manual"
+    };
+    if (this.pluginHost) {
+      const compactPayload = await this.pluginHost.runMiddleware("context.compact.before", payload, {
+        ...this.createHookContext(),
+        services: this.services
+      });
+      await this.pluginHost.runObservers("context.compact.before", compactPayload, {
+        ...this.createHookContext(),
+        services: this.services
+      });
+    }
+    await this.compactionService.apply({
+      sessionId: this.id,
+      ...update,
+      reason: update.reason ?? "manual"
+    });
+    const afterState = this.getCompactionState();
+    const latestCheckpoint = afterState.checkpoints.at(-1);
+    await this.notificationBus.emit({
+      type: "context.compacted",
+      source: "runtime",
+      level: "info",
+      message: `Context compacted for session ${this.id}`,
+      metadata: {
+        cursor: afterState.cursor,
+        checkpointId: latestCheckpoint?.id,
+        reason: latestCheckpoint?.reason
+      }
+    }, {
+      ...this.createHookContext()
+    });
+  }
   async save() {
     if (!this.stateStore)
       return;
     let snapshot = this.toSnapshot();
     if (this.pluginHost) {
-      const payload = await this.pluginHost.runMiddleware("snapshot.encode", { snapshot }, {
-        sessionId: this.id,
-        cwd: this.state.cwd,
-        metadata: this.state.metadata,
+      snapshot = await this.pluginHost.runMiddleware("snapshot.encode", { snapshot }, {
+        ...this.createHookContext(),
         services: this.services
-      });
-      snapshot = payload.snapshot;
+      }).then((payload) => payload.snapshot);
     }
     await this.stateStore.save(snapshot);
+    await this.notificationBus.emit({
+      type: "snapshot.saved",
+      source: "persistence",
+      level: "info",
+      message: `Saved snapshot for session ${this.id}`,
+      metadata: {
+        sessionId: this.id,
+        schemaVersion: snapshot.schemaVersion
+      }
+    }, {
+      ...this.createHookContext()
+    });
   }
   toSnapshot() {
     return sessionSnapshotCodec.encode({
@@ -1661,6 +2593,8 @@ class Session {
       cwd: this.state.cwd,
       messages: this.messages,
       usage: this.usage,
+      compaction: this.getCompactionState(),
+      pluginState: this.listPluginStates(),
       createdAt: this.createdAt,
       updatedAt: this.updatedAt,
       metadata: this.state.metadata ? { ...this.state.metadata } : undefined
@@ -1682,12 +2616,17 @@ class Session {
   }
   async* stream(input, options) {
     const runner = this.createLoopRunner();
-    return yield* runner.run(this.state, input, {
-      signal: options?.signal,
-      onDone: async () => {
-        await this.save();
-      }
-    });
+    this.activeRunCount += 1;
+    try {
+      return yield* runner.run(this.state, input, {
+        signal: options?.signal,
+        onDone: async () => {
+          await this.save();
+        }
+      });
+    } finally {
+      this.activeRunCount = Math.max(0, this.activeRunCount - 1);
+    }
   }
   createLoopRunner() {
     return new LoopRunner({
@@ -1698,13 +2637,43 @@ class Session {
         tools: this.state.tools,
         metadata: this.state.metadata,
         services: this.services,
-        pluginHost: this.pluginHost
+        pluginHost: this.pluginHost,
+        approvalManager: this.approvalManager,
+        notificationBus: this.notificationBus
       }),
       terminationPolicy: new DefaultTerminationPolicy,
       contextManager: this.contextManager,
-      pluginHost: this.pluginHost
+      pluginHost: this.pluginHost,
+      notificationBus: this.notificationBus
     });
   }
+  async readEstimatedInputTokens() {
+    if (!this.state.compactionOptions || this.state.compactionOptions.enabled === false)
+      return 0;
+    const projectedMessages = projectMessagesForRequest(this.state.messages, this.state.compaction);
+    const promptSegments = buildCompactionPromptSegments(this.state.compaction);
+    const requestMessages = [...projectedMessages];
+    if (promptSegments.length > 0)
+      requestMessages.unshift(new DefaultMessageFactory().createSystemMessage(promptSegments.join(`
+
+`)));
+    const budget = await estimateCompactionBudget(this.state.compactionOptions, {
+      model: this.state.modelRef,
+      messages: requestMessages,
+      tools: this.state.tools?.definitions() ?? []
+    });
+    return budget.estimatedInputTokens;
+  }
+  createHookContext(input = {}) {
+    return {
+      sessionId: this.id,
+      requestId: input.requestId,
+      iteration: input.iteration,
+      cwd: this.state.cwd,
+      metadata: this.state.metadata,
+      status: this.getStatus()
+    };
+  }
 }
 
 // src/agent-core/Agent.ts
@@ -1719,13 +2688,23 @@ class Agent {
   contextManager;
   tracker;
   permissionGateway;
+  approvalManager;
+  notificationBus;
+  compactionService;
+  pluginStateService;
   constructor(options) {
     this.id = createId("agent");
     this.options = options;
     this.permissions = options.permissions;
+    validateCompactionOwner(options);
     this.tracker = new ActivityTracker;
-    this.services = createServices(options, this.tracker);
-    this.permissionGateway = new PermissionGateway({ permissions: options.permissions });
+    this.compactionService = new DefaultCompactionService;
+    this.pluginStateService = new DefaultPluginStateService;
+    this.services = createServices(options, this.tracker, this.compactionService, this.pluginStateService);
+    this.permissionGateway = new PermissionGateway({
+      permissions: options.permissions,
+      compactionOwnerPluginId: options.compaction?.ownerPluginId
+    });
     this.pluginHost = new PluginHost({
       agentId: this.id,
       cwd: options.cwd,
@@ -1734,6 +2713,14 @@ class Agent {
       permissionGateway: this.permissionGateway,
       tracker: this.tracker
     });
+    this.notificationBus = new DefaultNotificationBus({
+      pluginHost: this.pluginHost,
+      services: this.services
+    });
+    this.approvalManager = new DefaultApprovalManager({
+      handler: options.approvalHandler,
+      notifications: this.notificationBus
+    });
     this.contextManager = options.contextManager ?? new AutoContextManager({
       services: this.services,
       pluginHost: this.pluginHost
@@ -1758,10 +2745,15 @@ class Agent {
       cwd: options.cwd ?? this.options.cwd,
       metadata: options.metadata ?? this.options.metadata,
       reasoning: this.options.reasoning,
+      compactionOptions: this.options.compaction,
       messages,
       pluginHost: this.pluginHost,
       contextManager: this.contextManager,
-      services: this.services
+      services: this.services,
+      approvalManager: this.approvalManager,
+      notificationBus: this.notificationBus,
+      compactionService: this.compactionService,
+      pluginStateService: this.pluginStateService
     });
   }
   async restoreSession(sessionId) {
@@ -1785,27 +2777,44 @@ class Agent {
       reasoning: this.options.reasoning,
       messages: snapshot.messages,
       usage: snapshot.usage,
+      compaction: snapshot.compaction,
+      pluginState: snapshot.pluginState,
+      compactionOptions: this.options.compaction,
       createdAt: snapshot.createdAt,
       updatedAt: snapshot.updatedAt,
       pluginHost: this.pluginHost,
       contextManager: this.contextManager,
-      services: this.services
+      services: this.services,
+      approvalManager: this.approvalManager,
+      notificationBus: this.notificationBus,
+      compactionService: this.compactionService,
+      pluginStateService: this.pluginStateService
     });
   }
 }
 function createAgent(options) {
   return new Agent(options);
 }
-function createServices(options, tracker) {
+function createServices(options, tracker, compaction, pluginState) {
   const exec = new NodeExecGateway({ cwd: options.cwd, tracker });
   return {
     fileSystem: new NodeFileSystemGateway({ cwd: options.cwd, tracker }),
     exec,
     git: new DefaultGitGateway({ exec, cwd: options.cwd }),
     network: new DefaultNetworkGateway,
-    model: new DefaultModelGateway(options.model)
+    model: new DefaultModelGateway(options.model),
+    compaction,
+    pluginState
   };
 }
+function validateCompactionOwner(options) {
+  const ownerPluginId = options.compaction?.ownerPluginId;
+  if (!ownerPluginId)
+    return;
+  const loadedPluginIds = new Set((options.plugins ?? []).map((plugin) => plugin.manifest.id));
+  if (!loadedPluginIds.has(ownerPluginId))
+    throw new Error(`Compaction owner plugin "${ownerPluginId}" is not loaded`);
+}
 function createToolRegistry(input) {
   const registry = input.tools instanceof ToolRegistry ? cloneRegistry(input.tools) : new ToolRegistry;
   if (input.includeBuiltinTools) {
@@ -2585,16 +3594,25 @@ function imageDataUrl(block) {
   return `data:${block.mimeType};base64,${block.data}`;
 }
 function messagesToOpenAI(messages) {
-  return messages.map((message) => {
+  const systemSegments = [];
+  const mappedMessages = [];
+  for (const message of messages) {
+    if (message.role === "system") {
+      const text = contentToText(message.content);
+      if (text)
+        systemSegments.push(text);
+      continue;
+    }
     if (message.role === "tool") {
-      return {
+      mappedMessages.push({
         role: "tool",
         tool_call_id: message.toolCallId,
         content: message.content.length > 0 ? contentToText(message.content) : JSON.stringify(message.structuredContent ?? {})
-      };
+      });
+      continue;
     }
     if (message.role === "assistant") {
-      return {
+      mappedMessages.push({
         role: "assistant",
         content: contentToText(message.content),
         tool_calls: message.toolCalls?.map((toolCall) => ({
@@ -2605,14 +3623,23 @@ function messagesToOpenAI(messages) {
             arguments: JSON.stringify(toolCall.function.arguments)
           }
         }))
-      };
+      });
+      continue;
     }
-    return {
+    mappedMessages.push({
       role: message.role,
       content: messageContentToOpenAI(message.content),
       ...message.role === "user" && message.name ? { name: message.name } : {}
-    };
-  });
+    });
+  }
+  if (systemSegments.length === 0)
+    return mappedMessages;
+  return [{
+    role: "system",
+    content: systemSegments.join(`
+
+`)
+  }, ...mappedMessages];
 }
 function normalizeOpenAIToolCalls(value) {
   if (!value)
@@ -2990,6 +4017,7 @@ export {
   DefaultNetworkGateway,
   DefaultModelGateway,
   DefaultGitGateway,
+  DefaultCompactionService,
   BaseTool,
   AutoContextManager,
   Agent,