mixdog 1.2.5 → 1.3.0

package/src/runtime/agent/orchestrator/session/human-gate/outbound-policy.mjs

@@ -0,0 +1,221 @@
+// session/human-gate/outbound-policy.mjs
+// Which calls post, send or spend outside the machine and so need the user's
+// approval by default: PR comment and review, issue comment, email or message
+// send, social publish, form submit, payment or purchase, and a permanent
+// delete. Classified by name against a small explicit list, with the tool's
+// annotations: a known send name stays outbound whatever the tool declares;
+// any other tool that declares itself read-only is never outbound, and an MCP
+// tool may opt in with `outboundHint: true`. Browser form submits are
+// confirmed by the desktop browser host itself (main/browser/action-approval.ts),
+// so `browser` is not classified here.
+//
+// The category is the "action kind" a remembered grant is keyed by (agent +
+// kind). Payments and permanent deletes are never remembered.
+
+/** Every action kind, in the order the profile's permission table lists them. */
+export const ACTION_KINDS = Object.freeze([
+  'comment',
+  'review',
+  'message',
+  'email',
+  'publish',
+  'form',
+  'payment',
+  'delete',
+  'trash',
+]);
+const UNREMEMBERED_ACTIONS = new Set(['payment', 'delete']);
+
+/** Whether "don't ask again" (an `allow` grant) may exist for `kind`. */
+export function isRememberableAction(kind) {
+  return ACTION_KINDS.includes(kind) && !UNREMEMBERED_ACTIONS.has(kind);
+}
+
+const GITHUB_OUTBOUND = new Map([
+  ['issue.comment', 'comment'],
+  ['pr.comment', 'comment'],
+  ['pr.review', 'review'],
+]);
+
+/** Bare MCP tool names (lowercase, `-` → `_`) and what they send. */
+const MCP_OUTBOUND = new Map([
+  ...[
+    'add_issue_comment',
+    'create_issue_comment',
+    'add_reply_to_pull_request_comment',
+    'add_comment_to_pending_review',
+    'add_pull_request_review_comment',
+  ].map((name) => [name, 'comment']),
+  ...['create_pull_request_review', 'create_and_submit_pull_request_review', 'submit_pending_pull_request_review'].map(
+    (name) => [name, 'review']
+  ),
+  ...['send_email', 'send_mail', 'gmail_send', 'gmail_send_email', 'send_gmail_message', 'reply_email'].map((name) => [
+    name,
+    'email',
+  ]),
+  ...[
+    'send_message',
+    'post_message',
+    'reply_to_message',
+    'slack_post_message',
+    'slack_reply_to_thread',
+    'chat_post_message',
+    'discord_send_message',
+    'telegram_send_message',
+  ].map((name) => [name, 'message']),
+  ...['create_post', 'publish_post', 'create_tweet', 'post_tweet', 'send_tweet'].map((name) => [name, 'publish']),
+  ['submit_form', 'form'],
+]);
+
+const PAYLOAD_FIELDS = ['body', 'text', 'message', 'content', 'comment', 'subject'];
+const TARGET_FIELDS = ['to', 'recipient', 'recipients', 'channel', 'channel_id', 'chat_id', 'thread', 'url', 'page'];
+
+// Name tokens (split on `_`) that make a send, a payment or a permanent delete.
+// A name opening with a read verb (list_payments, get_purchase) only reads.
+const READ_VERBS = new Set([
+  'get',
+  'list',
+  'search',
+  'read',
+  'fetch',
+  'retrieve',
+  'find',
+  'view',
+  'describe',
+  'lookup',
+]);
+const MAIL_TOKENS = new Set(['mail', 'email', 'gmail', 'outlook', 'smtp']);
+const SEND_TOKENS = new Set(['send', 'reply', 'forward']);
+const PAYMENT_TOKENS = new Set(['pay', 'payment', 'purchase', 'buy', 'checkout', 'charge']);
+const PAYMENT_NAMES = new Set(['place_order', 'send_money', 'transfer_money', 'transfer_funds']);
+const PERMANENT_TOKENS = new Set(['permanent', 'permanently', 'hard', 'forever']);
+
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const bareName = (value) =>
+  String(value || '')
+    .toLowerCase()
+    .replace(/-/g, '_');
+const tokensOf = (value) =>
+  bareName(value)
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+
+function payloadOf(args, fields) {
+  const editable = fields.filter((name) => typeof args[name] === 'string');
+  return { payload: editable.length ? String(args[editable[0]]) : '', editable };
+}
+
+const firstOf = (args, names) => {
+  for (const name of names) {
+    const value = args[name];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+    if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+    if (Array.isArray(value) && value.length) return value.map(String).join(', ');
+  }
+  return '';
+};
+
+/** The category a bare MCP tool name (and its server) makes, or ''. */
+function categoryByName(bare, server) {
+  const tokens = tokensOf(bare);
+  const listed = MCP_OUTBOUND.get(bare) || '';
+  if (READ_VERBS.has(tokens[0])) return listed;
+  const mail = [...tokens, ...tokensOf(server)].some((token) => MAIL_TOKENS.has(token));
+  if (mail && tokens.some((token) => SEND_TOKENS.has(token))) return 'email';
+  if (listed) return listed;
+  if (PAYMENT_NAMES.has(bare) || tokens.some((token) => PAYMENT_TOKENS.has(token))) return 'payment';
+  if (bare === 'empty_trash' || tokens.includes('purge')) return 'delete';
+  // Recoverable (Gmail Trash): asks, and unlike a permanent delete it may be remembered.
+  if (bare === 'trash_emails') return 'trash';
+  if (tokens.includes('delete') && tokens.some((token) => PERMANENT_TOKENS.has(token))) return 'delete';
+  return '';
+}
+
+/** What a card shows besides the payload: mail headers, the payment, the delete (empty lines left out). */
+function detailsOf(category, args) {
+  return Object.fromEntries(Object.entries(detailLines(category, args)).filter(([, value]) => value));
+}
+
+function detailLines(category, args) {
+  if (category === 'email') {
+    return {
+      to: firstOf(args, ['to', 'recipient', 'recipients']),
+      cc: firstOf(args, ['cc']),
+      subject: firstOf(args, ['subject']),
+    };
+  }
+  if (category === 'payment') {
+    return {
+      merchant: firstOf(args, ['merchant', 'payee', 'vendor', 'seller', 'recipient', 'to', 'description']),
+      amount: firstOf(args, ['amount', 'price', 'total', 'value']),
+      currency: firstOf(args, ['currency']).toUpperCase(),
+      recurrence: firstOf(args, ['recurrence', 'interval', 'frequency', 'billing_cycle']),
+    };
+  }
+  if (category === 'trash') return { count: String(Array.isArray(args.ids) ? args.ids.length : 1) };
+  if (category === 'delete') {
+    const listed = ['ids', 'paths', 'files', 'file_ids', 'items'].map((name) => args[name]).find(Array.isArray);
+    return {
+      count: firstOf(args, ['count']) || String(listed ? listed.length : 1),
+      size: firstOf(args, ['size', 'total_size', 'bytes']),
+    };
+  }
+  return {};
+}
+
+function mcpTarget(args, server) {
+  const repo = [args.owner, args.repo].filter((part) => typeof part === 'string' && part).join('/');
+  const number = args.issue_number ?? args.pull_number ?? args.number;
+  if (repo) return number != null ? `${repo}#${number}` : repo;
+  for (const name of TARGET_FIELDS) {
+    const value = args[name];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+    if (Array.isArray(value) && value.length) return value.map(String).join(', ');
+  }
+  return server;
+}
+
+/**
+ * `{ category, tool, target, account, payload, editable, details }` for a call
+ * that posts, sends, pays or permanently deletes, else null. `category` is the
+ * action kind; `tool` the GitHub action or the MCP tool's full name.
+ */
+export function classifyOutboundCall({ name, args, annotations } = {}) {
+  const input = isRecord(args) ? args : {};
+  const toolName = String(name || '');
+  if (toolName === 'github') {
+    const category = GITHUB_OUTBOUND.get(input.action);
+    if (!category) return null;
+    return {
+      category,
+      tool: `github:${input.action}`,
+      target: `${input.repo || '(current project)'}#${input.number ?? '?'}`,
+      account: String(input.hostname || 'github.com'),
+      ...payloadOf(input, ['body']),
+      details: {},
+    };
+  }
+  if (!toolName.startsWith('mcp__')) return null;
+  const [, server = '', ...rest] = toolName.split('__');
+  const bare = bareName(annotations?.mcpToolName || rest.join('__'));
+  let category = categoryByName(bare, server);
+  if (!category && tokensOf(bare).includes('delete') && input.permanent === true) category = 'delete';
+  // A known send, payment or delete name stays outbound whatever the tool says.
+  if (!category && annotations?.readOnlyHint === true) return null;
+  if (!category && annotations?.outboundHint === true) category = 'message';
+  if (!category) return null;
+  const details = detailsOf(category, input);
+  const spends = category === 'payment' || category === 'delete';
+  return {
+    category,
+    tool: toolName,
+    target:
+      (category === 'payment' && details.merchant) ||
+      (category === 'trash' && firstOf(input, ['ids'])) ||
+      (category === 'delete' && firstOf(input, ['path', 'name', 'folder', 'paths', 'ids', 'file_ids'])) ||
+      mcpTarget(input, server),
+    account: (category === 'email' && firstOf(input, ['from', 'account'])) || server,
+    ...(spends || category === 'trash' ? { payload: '', editable: [] } : payloadOf(input, PAYLOAD_FIELDS)),
+    details,
+  };
+}

package/src/runtime/agent/orchestrator/session/human-gate/requests.mjs

@@ -0,0 +1,195 @@
+// session/human-gate/requests.mjs
+// The data model of a human-in-the-loop prompt. A request has one `kind`:
+//   approval   — allow or deny one tool call;
+//   outbound   — a call that posts, sends, pays or deletes outside (its action
+//                kind, target, account, the exact payload text, which fields
+//                the card may edit, and the mail/payment/delete detail lines);
+//   secret     — the user types a value into a target field; the request names
+//                the target and the field label, never a value;
+//   takeover   — the user does a step themselves and says "done";
+//   permission — the user picks one of the offered scopes.
+// A response is one of HUMAN_RESPONSES plus a `remember` scope; a policy lists
+// the scopes it allows and can leave out `always`. Nothing here ever carries a
+// secret value: a decision that names one is stripped to its verdict.
+
+export const HUMAN_REQUEST_KINDS = Object.freeze(['approval', 'outbound', 'secret', 'takeover', 'permission']);
+export const HUMAN_RESPONSES = Object.freeze(['approve', 'deny', 'edit-and-approve', 'provide-secret', 'skip', 'done']);
+export const REMEMBER_SCOPES = Object.freeze(['once', 'agent', 'always']);
+export const SECRET_REQUEST_TIMEOUT_MS = 120_000;
+
+const RESPONSES_BY_KIND = Object.freeze({
+  approval: ['approve', 'deny'],
+  outbound: ['approve', 'edit-and-approve', 'deny'],
+  secret: ['provide-secret', 'skip'],
+  takeover: ['done', 'deny'],
+  permission: ['approve', 'deny'],
+});
+const GRANTING_RESPONSES = new Set(['approve', 'edit-and-approve', 'provide-secret', 'done']);
+const TEXT_LIMIT = 200;
+/** An outbound card's extra lines: mail headers, the payment, the delete, the
+ *  trash card's message list (gate.mjs describeEmails) and its remainder. */
+const DETAIL_FIELDS = [
+  'to',
+  'cc',
+  'subject',
+  'merchant',
+  'amount',
+  'currency',
+  'recurrence',
+  'count',
+  'size',
+  'messages',
+  'more',
+];
+const DETAIL_LIMITS = { messages: 1_000 };
+const PAYLOAD_LIMIT = 40_000;
+
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const text = (value, limit = TEXT_LIMIT) => (typeof value === 'string' ? value.trim().slice(0, limit) : '');
+
+/** The human kind of a request; anything else (ask_user's 'question', a
+ *  hook's bare ask) is an ordinary approval for responses. */
+export function humanRequestKind(request) {
+  return HUMAN_REQUEST_KINDS.includes(request?.kind) ? request.kind : 'approval';
+}
+
+/** A login takeover's sign-in page: https, or http on loopback only (a local
+ *  site); never embedded credentials. `{ url, origin }`, or null. */
+export function loginPageUrl(value) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 2048) return null;
+  let parsed;
+  try {
+    parsed = new URL(value.trim());
+  } catch {
+    return null;
+  }
+  const host = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  const loopback =
+    host === 'localhost' || host.endsWith('.localhost') || host === '::1' || /^127(?:\.\d{1,3}){3}$/.test(host);
+  if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && loopback)) return null;
+  if (parsed.username || parsed.password) return null;
+  return { url: parsed.href, origin: parsed.origin };
+}
+
+function rememberScopes(value) {
+  const listed = Array.isArray(value) ? value.filter((scope) => REMEMBER_SCOPES.includes(scope)) : [];
+  return ['once', ...new Set(listed.filter((scope) => scope !== 'once'))];
+}
+
+/** The kind-specific fields of a request, whitelisted. Spread onto the
+ *  presented request; `args` is replaced for a secret so no value rides it. */
+export function humanRequestFields(input = {}) {
+  const kind = input?.kind;
+  if (!HUMAN_REQUEST_KINDS.includes(kind)) return {};
+  const fields = { remember: rememberScopes(input.remember) };
+  // The agent the request acts for (its name on the card and the remembered grant).
+  if (text(input.agentId)) fields.agentId = text(input.agentId);
+  if (kind === 'outbound' && isRecord(input.outbound)) {
+    const outbound = input.outbound;
+    const details = isRecord(outbound.details) ? outbound.details : {};
+    fields.outbound = {
+      category: text(outbound.category),
+      target: text(outbound.target),
+      account: text(outbound.account),
+      payload: typeof outbound.payload === 'string' ? outbound.payload.slice(0, PAYLOAD_LIMIT) : '',
+      editable: Array.isArray(outbound.editable) ? outbound.editable.filter((name) => typeof name === 'string') : [],
+      details: Object.fromEntries(
+        DETAIL_FIELDS.filter((name) => text(details[name])).map((name) => [
+          name,
+          text(details[name], DETAIL_LIMITS[name]),
+        ])
+      ),
+    };
+  }
+  if (kind === 'secret') {
+    const secret = isRecord(input.secret) ? input.secret : {};
+    fields.secret = {
+      requestId: text(secret.requestId),
+      surface: secret.surface === 'computer' ? 'computer' : 'browser',
+      target: text(secret.target),
+      field: text(secret.field),
+    };
+    fields.args = { surface: fields.secret.surface, target: fields.secret.target, field: fields.secret.field };
+    fields.remember = ['once'];
+  }
+  if (kind === 'takeover') {
+    const takeover = isRecord(input.takeover) ? input.takeover : {};
+    const surface = takeover.surface === 'computer' ? 'computer' : 'browser';
+    // The window it is about (ask-user-tool-defs.mjs handoffIdentity): a
+    // browser page ID, or a computer window id and app, so the card can bring
+    // exactly that window forward on the user's click.
+    const token = (value, limit) => (/^[\w.:#@-]+$/.test(text(value, limit)) ? text(value, limit) : '');
+    const identity =
+      surface === 'browser'
+        ? { ...(token(takeover.tab, 64) ? { tab: token(takeover.tab, 64) } : {}) }
+        : {
+            ...(token(takeover.windowId, 128) ? { windowId: token(takeover.windowId, 128) } : {}),
+            ...(text(takeover.app, 120) ? { app: text(takeover.app, 120) } : {}),
+          };
+    // A login takeover (purpose 'login') opens the desktop's sign-in window on
+    // its validated page instead of handing over the side panel.
+    const login = surface === 'browser' && takeover.purpose === 'login' ? loginPageUrl(takeover.url) : null;
+    fields.takeover = {
+      surface,
+      instructions: text(takeover.instructions, 2_000),
+      ...(text(takeover.target) ? { target: text(takeover.target) } : {}),
+      ...identity,
+      ...(login ? { purpose: 'login', url: login.url, origin: login.origin } : {}),
+    };
+    fields.remember = ['once'];
+  }
+  if (kind === 'permission') {
+    const scopes = Array.isArray(input.permission?.scopes) ? input.permission.scopes : [];
+    fields.permission = {
+      scopes: scopes
+        .filter((scope) => isRecord(scope) && text(scope.id))
+        .map((scope) => ({ id: text(scope.id), label: text(scope.label) || text(scope.id) })),
+    };
+  }
+  return fields;
+}
+
+/** Only `editable` string fields of `editedArgs`; {} when nothing applies. */
+function editableArgs(editedArgs, editable) {
+  if (!isRecord(editedArgs)) return {};
+  const out = {};
+  for (const name of editable || []) {
+    if (typeof editedArgs[name] === 'string') out[name] = editedArgs[name].slice(0, PAYLOAD_LIMIT);
+  }
+  return out;
+}
+
+/**
+ * The canonical response to `request` from a decision: `approved` (the card's
+ * polarity) plus optional `{ response, editedArgs, remember, scope }`. An
+ * unknown or contradicting response falls back to the polarity's default;
+ * edits survive only on an outbound request and only for its editable fields;
+ * `remember` only when the request allows it and the call was granted.
+ */
+export function normalizeHumanResponse(request, approved, extra = {}) {
+  const kind = humanRequestKind(request);
+  const allowed = RESPONSES_BY_KIND[kind];
+  const polarity = approved === true;
+  const fallback = polarity ? allowed[0] : allowed[allowed.length - 1];
+  const asked = isRecord(extra) && allowed.includes(extra.response) ? extra.response : '';
+  let response = asked && GRANTING_RESPONSES.has(asked) === polarity ? asked : fallback;
+  const result = { approved: polarity, response };
+  if (response === 'edit-and-approve') {
+    const edits = editableArgs(extra.editedArgs, request?.outbound?.editable);
+    if (Object.keys(edits).length) result.editedArgs = edits;
+    else response = result.response = 'approve';
+  }
+  const scopes = Array.isArray(request?.remember) ? request.remember : ['once'];
+  result.remember = polarity && scopes.includes(extra?.remember) ? extra.remember : 'once';
+  if (kind === 'permission' && polarity) {
+    const ids = (request?.permission?.scopes || []).map((scope) => scope.id);
+    if (ids.includes(extra?.scope)) result.scope = extra.scope;
+  }
+  return result;
+}
+
+/** `args` with the card's edited fields in place of the model's. */
+export function applyEditedArgs(args, editedArgs, editable) {
+  const edits = editableArgs(editedArgs, editable);
+  return Object.keys(edits).length ? { ...(isRecord(args) ? args : {}), ...edits } : args;
+}

package/src/runtime/agent/orchestrator/session/human-gate/store.mjs

@@ -0,0 +1,167 @@
+// session/human-gate/store.mjs
+// Per-agent permissions and the decision audit, both under the plugin data dir.
+// A grant is keyed by agent + action kind (outbound-policy.mjs ACTION_KINDS)
+// and says `allow` (never ask: "다시 묻지 않기") or `block` (deny without a
+// card); no grant means ask. `agent` scope names the agent, `always` stands for
+// every agent ('*'), and an agent's own grant wins over an every-agent one;
+// `once` is never stored. Payments and deletes are never allowed. Grants are
+// listed and revoked by id. The audit is one JSONL line per decision with
+// agent, kind, action, tool, target, decision, deciding device and time —
+// never a value, an argument or a payload — read back newest first.
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { parseJsonText, updateJsonAtomic } from '../../../../shared/atomic-file.mjs';
+import { ACTION_KINDS, isRememberableAction } from './outbound-policy.mjs';
+
+const ANY_AGENT = '*';
+const FIELD_LIMIT = 200;
+const AUDIT_KEYS = ['agentId', 'kind', 'action', 'tool', 'target', 'decision', 'device'];
+export const PERMISSION_MODES = Object.freeze(['ask', 'allow', 'block']);
+
+const field = (value) => String(value ?? '').slice(0, FIELD_LIMIT);
+const grantId = (agentId, action) =>
+  `grant_${createHash('sha256').update(`${agentId}\n${action}`).digest('hex').slice(0, 24)}`;
+const isGrant = (row) => ACTION_KINDS.includes(row?.action) && (row.mode === 'allow' || row.mode === 'block');
+
+export function createHumanGateStore(directory) {
+  const grantsFile = join(directory, 'grants.json');
+  const auditFile = join(directory, 'audit.jsonl');
+  const grantsOf = (doc) => (Array.isArray(doc?.grants) ? doc.grants.filter(isGrant) : []);
+  async function readGrants() {
+    try {
+      return grantsOf(parseJsonText(await readFile(grantsFile, 'utf8')));
+    } catch (error) {
+      if (error?.code === 'ENOENT') return [];
+      throw error;
+    }
+  }
+  async function updateGrants(mutate) {
+    await mkdir(directory, { recursive: true });
+    let result;
+    await updateJsonAtomic(grantsFile, (doc) => {
+      const out = mutate(grantsOf(doc));
+      if (!out) return undefined;
+      result = out.result;
+      return { grants: out.grants };
+    });
+    return result;
+  }
+  /** Set `agentId`'s mode for `action`; `ask` removes its grant. Returns the
+   *  grant, or null for `ask` and for an `allow` that may not exist. */
+  async function setMode({ agentId, action, mode, device = '' }) {
+    if (!ACTION_KINDS.includes(action) || !PERMISSION_MODES.includes(mode)) return null;
+    if (mode === 'allow' && !isRememberableAction(action)) return null;
+    const owner = field(agentId);
+    const id = grantId(owner, action);
+    const grant = mode === 'ask' ? null : { id, agentId: owner, action, mode, device: field(device), at: Date.now() };
+    await updateGrants((grants) => ({
+      grants: [...grants.filter((row) => row.id !== id), ...(grant ? [grant] : [])],
+      result: grant,
+    }));
+    return grant;
+  }
+  /** `allow`, `block` or `ask` for `agentId` + `action`; the agent's own grant wins. */
+  async function modeFor({ agentId, action }) {
+    const grants = (await readGrants()).filter((grant) => grant.action === action);
+    const own =
+      grants.find((grant) => grant.agentId === agentId) || grants.find((grant) => grant.agentId === ANY_AGENT);
+    if (own?.mode === 'allow' && !isRememberableAction(action)) return 'ask';
+    return own?.mode || 'ask';
+  }
+  return {
+    setMode,
+    modeFor,
+    /** Stores an `allow` for `agent`/`always` scope; `once` stores nothing. Returns the grant or null. */
+    async grant({ agentId, action, scope, device = '' }) {
+      if (scope !== 'agent' && scope !== 'always') return null;
+      return setMode({ agentId: scope === 'always' ? ANY_AGENT : agentId, action, mode: 'allow', device });
+    },
+    /** Every action kind with `agentId`'s mode, for the profile's permission table. */
+    async permissions(agentId) {
+      const out = [];
+      for (const action of ACTION_KINDS) {
+        out.push({ action, mode: await modeFor({ agentId, action }), rememberable: isRememberableAction(action) });
+      }
+      return out;
+    },
+    /** Grants that apply to `agentId` (its own and every-agent ones); all when omitted. */
+    async listGrants({ agentId } = {}) {
+      const grants = await readGrants();
+      return agentId ? grants.filter((grant) => grant.agentId === agentId || grant.agentId === ANY_AGENT) : grants;
+    },
+    async revokeGrant(id) {
+      return (
+        (await updateGrants((grants) => {
+          const rest = grants.filter((grant) => grant.id !== id);
+          return rest.length === grants.length ? null : { grants: rest, result: true };
+        })) === true
+      );
+    },
+    async recordAudit(entry) {
+      const line = { at: Number.isFinite(entry?.at) ? entry.at : Date.now() };
+      for (const key of AUDIT_KEYS) line[key] = field(entry?.[key]);
+      await mkdir(dirname(auditFile), { recursive: true });
+      await appendFile(auditFile, `${JSON.stringify(line)}\n`, 'utf8');
+      return line;
+    },
+    /** Newest first; `agentId` filters to one agent. */
+    async readAudit({ agentId = '', limit = 100 } = {}) {
+      let raw = '';
+      try {
+        raw = await readFile(auditFile, 'utf8');
+      } catch (error) {
+        if (error?.code === 'ENOENT') return [];
+        throw error;
+      }
+      const rows = [];
+      for (const line of raw.split('\n').reverse()) {
+        if (!line) continue;
+        try {
+          const row = JSON.parse(line);
+          if (!agentId || row.agentId === agentId) rows.push(row);
+        } catch {}
+        if (rows.length >= limit) break;
+      }
+      return rows;
+    },
+  };
+}
+
+let processStore = null;
+/** The process store under the plugin data dir; built on first use. */
+export async function humanGateStore() {
+  if (!processStore) {
+    const { getPluginData } = await import('../../config.mjs');
+    processStore = createHumanGateStore(join(getPluginData(), 'human-gate'));
+  }
+  return processStore;
+}
+
+function requiredAgentId(agentId) {
+  if (typeof agentId !== 'string' || !agentId.trim() || agentId.length > FIELD_LIMIT || agentId === ANY_AGENT) {
+    throw new Error('agent id is invalid');
+  }
+  return agentId;
+}
+
+/** The profile's "권한" table for `agentId` (capability getAgentPermissions). */
+export async function agentPermissions(agentId) {
+  return (await humanGateStore()).permissions(requiredAgentId(agentId));
+}
+
+/** Set one row of that table (capability setAgentPermission); returns the table. */
+export async function setAgentPermission(agentId, action, mode) {
+  const agent = requiredAgentId(agentId);
+  if (!ACTION_KINDS.includes(action)) throw new Error(`action must be one of ${ACTION_KINDS.join(', ')}`);
+  if (!PERMISSION_MODES.includes(mode)) throw new Error(`mode must be one of ${PERMISSION_MODES.join(', ')}`);
+  if (mode === 'allow' && !isRememberableAction(action)) throw new Error(`${action} always asks; it cannot be allowed`);
+  const store = await humanGateStore();
+  await store.setMode({ agentId: agent, action, mode });
+  return store.permissions(agent);
+}
+
+/** Replace the process store (tests); null restores the default. */
+export function setHumanGateStore(store) {
+  processStore = store || null;
+}

package/src/runtime/agent/orchestrator/session/lifecycle-scan.mjs

@@ -189,6 +189,15 @@ export function readTopLevelLifecycleRecord(raw) {
   // — for EVERY top-level key, since consumers reserialize and act on the
   // whole record, not only on the lifecycle three.
   if (!hasUniqueTopLevelKeys(raw)) return LIFECYCLE_SCAN_CONFLICT;
+  return lifecycleRecordOf(doc);
+}
+
+/**
+ * Step 3 alone, for a reader that has already proven `doc` is the complete,
+ * well-formed, duplicate-free top-level object of its document (see
+ * store-record-strict-scan.mjs): the record, or LIFECYCLE_SCAN_CONFLICT.
+ */
+export function lifecycleRecordOf(doc) {
   const has = (key) => Object.hasOwn(doc, key);
   const record = { doc, id: undefined, closed: undefined, generation: undefined };
   if (has('id')) {

package/src/runtime/agent/orchestrator/session/loop/compact-policy.mjs

@@ -17,6 +17,7 @@ import { HANDOFF_TIMEOUT_MAX_MS } from '../compact/constants.mjs';
 import { envFlag, envPositiveInt } from '../../../../shared/env.mjs';
 import { positiveInt } from '../../../../shared/numbers.mjs';
 import { isAgentOwner } from '../../agent-owner.mjs';
+import { isAgentModeSession } from '../agent-mode.mjs';
 import { providerInputExcludesCache, providerNativePdf } from '../../providers/registry.mjs';
 import { contentMediaBytes, contentMediaCount } from '../../providers/media-normalization.mjs';
 import { splitProtectedContext } from '../compact/messages.mjs';
@@ -133,7 +134,8 @@ function effectiveContextWindowPercent(sessionRef, cfg) {
 export function resolveWorkerCompactPolicy(sessionRef, tools) {
   if (!sessionRef) return null;
   const cfg = sessionRef.compaction || {};
-  const auto = cfg.auto !== false && envFlag('MIXDOG_AGENT_COMPACT_AUTO', true);
+  // Agent mode always compacts on its own: the user is never asked to.
+  const auto = (cfg.auto !== false || isAgentModeSession(sessionRef)) && envFlag('MIXDOG_AGENT_COMPACT_AUTO', true);
   if (!auto) return { auto: false };
   const { contextWindow, boundaryTokens } = compactBoundaryFor(sessionRef, cfg);
   if (!boundaryTokens) return null;