@moxxy/sdk 0.44.0 → 0.46.0

package/src/mode/react-loop.ts

@@ -1,10 +1,7 @@
 import { isContextOverflowError, runCompactionIfNeeded } from '../compactor-helpers.js';
 import { runElisionIfNeeded } from '../elision-helpers.js';
 import type { MoxxyEvent } from '../events.js';
-import { asPluginId } from '../ids.js';
 import type { ModeContext } from '../mode.js';
-import type { TokenUsage } from '../provider.js';
-import type { StopReason } from '../provider-utils.js';
 import { usageEventFields } from '../token-accounting.js';
 import {
   emitRequestsAndDetectStuck,
@@ -14,8 +11,9 @@ import {
   type StuckTripInfo,
 } from '../tool-dispatch.js';
 import { nextBackoffMs, sleepWithAbort } from './abort-backoff.js';
-import type { CheckpointResult, TurnCheckpoint } from './checkpoint.js';
-import { collectProviderStream, type CollectedToolUse } from './collect-stream.js';
+import { emitAbort, emitError, runCheckpointGate } from './checkpoint-gate.js';
+import { runAgentStepLoop } from './agent-step-loop.js';
+import { collectProviderStream } from './collect-stream.js';
 import { buildSystemPromptWithSkills, projectMessages, skillsWithinReach } from './project-messages.js';
 import { createStuckLoopDetector } from './stuck-loop.js';
 
@@ -44,8 +42,6 @@ const DEFAULT_MAX_ITERATIONS = 500;
 const MAX_REACTIVE_COMPACTIONS = 2;
 const DEFAULT_MAX_INJECTIONS = 3;
 const DEFAULT_MAX_INJECT_CHARS = 16_384;
-const DEFAULT_CHECKPOINT_TIMEOUT_MS = 120_000;
-const CHECKPOINT_EVENT_PLUGIN_ID = asPluginId('react-loop');
 
 // Abort-aware sleep, injectable for tests so back-off paths run instantly and
 // deterministically. Production delegates to sleepWithAbort: a real timer that
@@ -70,115 +66,18 @@ export function __setRetrySleepForTests(
   };
 }
 
-/** What a clean provider call produced — input to {@link ReactLoopOptions.onProviderSuccess}. */
-export interface ProviderSuccessInfo {
-  readonly text: string;
-  readonly stopReason: StopReason;
-  readonly toolUses: ReadonlyArray<CollectedToolUse>;
-  readonly usage?: TokenUsage;
-  readonly iteration: number;
-}
-
-/** A completed tool batch — input to {@link ReactLoopOptions.onToolBatchEnd}. */
-export interface ToolBatchInfo {
-  readonly toolUses: ReadonlyArray<CollectedToolUse>;
-  readonly iteration: number;
-}
-
-/** Hooks return this to end the turn; the hook emits its own wrap-up events first. */
-export interface StopDirective {
-  readonly action: 'stop';
-}
-
-export interface ReactLoopOptions {
-  /** Name stamped on `mode_iteration` events (e.g. `'default'`, `'goal'`). */
-  readonly strategyName: string;
-  /**
-   * Iteration cap when the context doesn't supply one. Default 500. May be
-   * `Number.POSITIVE_INFINITY` for an uncapped loop (goal mode): the run then
-   * ends only via a terminal signal (checkpoint/hook stop, abort, fatal
-   * error) — an explicit `ctx.maxIterations` still takes precedence.
-   */
-  readonly defaultMaxIterations?: number;
-  /** Prefix for provider-error messages (goal mode uses `'goal: '`). */
-  readonly errorPrefix?: string;
-  /**
-   * When set, an already-aborted signal is reported (with this reason) BEFORE
-   * the first iteration — goal/collab preflight. When omitted the first
-   * iteration's own abort check covers it with the generic reason.
-   */
-  readonly preflightAbortReason?: string;
-  /** Turn-end gates, run in declared order. Omit/empty → plain ReAct loop. */
-  readonly checkpoints?: ReadonlyArray<TurnCheckpoint>;
-  /**
-   * Hard cap on checkpoint `inject`/`retry` rounds per idle EPISODE — i.e.
-   * consecutive gate rounds with no tool work between them; the count resets
-   * whenever a tool batch executes (default 3). When exhausted the turn ends
-   * with the model's answer as-is plus a visible warning — a
-   * permanently-failing gate degrades loudly instead of looping forever.
-   */
-  readonly maxInjections?: number;
-  /** Clamp on injected feedback length in characters (default 16_384). */
-  readonly maxInjectChars?: number;
-  /**
-   * Stuck-loop policy + wording overrides; sensible defaults from
-   * `strategyName`. `action` picks what a detector trip does:
-   *
-   *   - `'abort'` (default): fail the batch and end the turn with a fatal
-   *     error — the historical behavior, right for attended modes where the
-   *     user is present to redirect.
-   *   - `'nudge'`: never stop. The batch still executes (repeated calls are
-   *     usually legitimate work — re-running a failing build between edits),
-   *     a visible warning + `extraOnStuck` events are emitted, the detector
-   *     resets, and `nudgeText` (or a default) rides the next provider call
-   *     as a volatile steer. For unattended modes (goal) where a heuristic
-   *     must never kill the run.
-   */
-  readonly stuck?: Partial<StuckLoopReport> & {
-    readonly action?: 'abort' | 'nudge';
-    /** Volatile steer for `'nudge'` trips; default wording when omitted. */
-    readonly nudgeText?: (info: StuckTripInfo) => string;
-  };
-  /**
-   * Runs after compaction/elision, before the provider call. May return a
-   * volatile user message to ride ONLY the next call (collab's inbox/pause
-   * awareness) — never appended to the log; the cache strategy is told via
-   * `volatileTailCount` so its tail breakpoint stays ahead of it.
-   */
-  readonly onIterationStart?: (
-    ctx: ModeContext,
-    iteration: number,
-  ) => Promise<{ readonly volatileUserText?: string } | undefined>;
-  /**
-   * Runs after every clean provider call (reasoning already logged, tools not
-   * yet executed). Return `{action: 'stop'}` to end the turn — the hook emits
-   * its own wrap-up events first (goal mode's token-budget backstop).
-   */
-  readonly onProviderSuccess?: (
-    ctx: ModeContext,
-    info: ProviderSuccessInfo,
-  ) => Promise<StopDirective | undefined>;
-  /**
-   * Runs after a tool batch executes cleanly. Return `{action: 'stop'}` to
-   * end the turn (goal/collab terminal-tool detection: `goal_complete`,
-   * `collab_done`); the hook emits its own completion events first.
-   */
-  readonly onToolBatchEnd?: (
-    ctx: ModeContext,
-    info: ToolBatchInfo,
-  ) => Promise<StopDirective | undefined>;
-  /**
-   * Replaces the default "exceeded maxIterations" fatal error — the hook
-   * emits its own cap-reached events (goal mode adds a plugin event and its
-   * own wording). The loop returns right after.
-   */
-  readonly onMaxIterations?: (ctx: ModeContext, maxIterations: number) => Promise<void>;
-}
+export type { ProviderSuccessInfo, ReactLoopOptions, StopDirective, ToolBatchInfo } from './react-loop-options.js';
+import type { ReactLoopOptions } from './react-loop-options.js';
 
 export async function* runReactLoop(
   ctx: ModeContext,
   opts: ReactLoopOptions,
 ): AsyncIterable<MoxxyEvent> {
+  // An agent connection: the vendor's agent does each round, not this loop.
+  if (ctx.provider.agentStep) {
+    yield* runAgentStepLoop(ctx, opts);
+    return;
+  }
   if (opts.preflightAbortReason && ctx.signal.aborted) {
     yield await emitAbort(ctx, opts.preflightAbortReason);
     return;
@@ -499,145 +398,6 @@ export async function* runReactLoop(
   );
 }
 
-/** Gate outcome: end the turn, or loop again (optionally with a volatile nudge). */
-type GateVerdict = { readonly kind: 'end' } | { readonly kind: 'loop'; readonly volatileText?: string };
-
-interface GateRound {
-  readonly candidateText: string;
-  readonly stopReason: StopReason;
-  readonly iteration: number;
-  readonly consecutiveIdle: number;
-  readonly injectionsUsed: number;
-  readonly injectionBudget: number;
-  readonly maxInjectChars: number;
-}
-
-async function* runCheckpointGate(
-  ctx: ModeContext,
-  checkpoints: ReadonlyArray<TurnCheckpoint>,
-  round: GateRound,
-): AsyncGenerator<MoxxyEvent, GateVerdict> {
-  // Natural completions face every checkpoint; truncated/errored candidates
-  // only face the idle-tolerant ones — reviewing a half-sentence as if it
-  // were a completion claim wastes a checker run and confuses the model.
-  const eligible = checkpoints.filter(
-    (cp) =>
-      (round.stopReason === 'end_turn' || (cp.gateOn ?? 'end_turn') === 'idle') && (cp.applies?.(ctx) ?? true),
-  );
-  if (eligible.length === 0) return { kind: 'end' };
-
-  // Budget exhausted → the answer ships as-is, but LOUDLY: silent
-  // degradation would let the user believe a gated answer passed its gates.
-  if (round.injectionsUsed >= round.injectionBudget) {
-    yield await emitError(
-      ctx,
-      'retryable',
-      `checkpoint budget exhausted (${round.injectionBudget} rounds) — ` +
-        `ending the turn with unresolved checkpoint feedback; verify the result manually.`,
-    );
-    return { kind: 'end' };
-  }
-
-  for (const cp of eligible) {
-    // User cancelled mid-gate: end the turn WITHOUT retracting the
-    // already-logged answer — an abort must never un-say what was said.
-    if (ctx.signal.aborted) return { kind: 'end' };
-
-    yield await emitCheckpointEvent(ctx, 'checkpoint_started', {
-      name: cp.name,
-      iteration: round.iteration,
-    });
-
-    const timeoutMs = Math.max(1_000, cp.timeoutMs ?? DEFAULT_CHECKPOINT_TIMEOUT_MS);
-    const timeoutCtl = new AbortController();
-    const timer = setTimeout(() => timeoutCtl.abort(), timeoutMs);
-    timer.unref?.();
-    let result: CheckpointResult;
-    try {
-      result = await cp.run(
-        {
-          candidateText: round.candidateText,
-          stopReason: round.stopReason,
-          iteration: round.iteration,
-          consecutiveIdle: round.consecutiveIdle,
-          injectionsUsed: round.injectionsUsed,
-          injectionBudget: round.injectionBudget,
-          signal: AbortSignal.any([ctx.signal, timeoutCtl.signal]),
-        },
-        ctx,
-      );
-    } catch (err) {
-      if (ctx.signal.aborted) return { kind: 'end' };
-      // Fail OPEN, visibly. A crashed or timed-out checker downgrades the
-      // gate to a warning — it must never wedge the turn (fail-closed is a
-      // turn that can never end) and never crash it (the answer is already
-      // logged).
-      const why = timeoutCtl.signal.aborted
-        ? `timed out after ${timeoutMs}ms`
-        : `failed: ${err instanceof Error ? err.message : String(err)}`;
-      yield await emitError(ctx, 'retryable', `checkpoint "${cp.name}" ${why} — proceeding unchecked`);
-      continue;
-    } finally {
-      clearTimeout(timer);
-    }
-
-    switch (result.action) {
-      case 'pass': {
-        yield await emitCheckpointEvent(ctx, 'checkpoint_passed', { name: cp.name });
-        continue;
-      }
-      case 'stop': {
-        // The checkpoint already emitted its own wrap-up events.
-        yield await emitCheckpointEvent(ctx, 'checkpoint_stopped', { name: cp.name });
-        return { kind: 'end' };
-      }
-      case 'retry': {
-        yield await emitCheckpointEvent(ctx, 'checkpoint_retry', { name: cp.name });
-        return { kind: 'loop' };
-      }
-      case 'inject': {
-        // Guard the guard: an inject with blank text would loop the turn
-        // with no new signal for the model — a checker bug; fail open.
-        const feedback = result.text?.trim();
-        if (!feedback) {
-          yield await emitError(
-            ctx,
-            'retryable',
-            `checkpoint "${cp.name}" injected empty feedback — ignored`,
-          );
-          continue;
-        }
-        const clamped = clampChars(feedback, round.maxInjectChars);
-        if (result.volatile) {
-          yield await emitCheckpointEvent(ctx, 'checkpoint_injected', {
-            name: cp.name,
-            volatile: true,
-          });
-          return { kind: 'loop', volatileText: clamped };
-        }
-        // Persistent: a checkpoint-origin user prompt. Projected as a
-        // user-role message by the existing projection case, marked via the
-        // same `origin` machinery trigger prompts use, cache-safe because it
-        // is an ordinary append at the log tail.
-        yield await ctx.emit({
-          type: 'user_prompt',
-          sessionId: ctx.sessionId,
-          turnId: ctx.turnId,
-          source: 'system',
-          text: clamped,
-          origin: { kind: 'checkpoint', name: cp.name },
-        });
-        yield await emitCheckpointEvent(ctx, 'checkpoint_injected', {
-          name: cp.name,
-          volatile: false,
-        });
-        return { kind: 'loop' };
-      }
-    }
-  }
-  return { kind: 'end' };
-}
-
 function defaultStuckNudge(trip: StuckTripInfo): string {
   return (
     `You have called the tool \`${trip.toolName}\` ${trip.count} times ${trip.how}. ` +
@@ -663,49 +423,3 @@ function buildStuckReport(opts: ReactLoopOptions): StuckLoopReport {
     ...(opts.stuck?.extraOnStuck ? { extraOnStuck: opts.stuck.extraOnStuck } : {}),
   };
 }
-
-function clampChars(text: string, max: number): string {
-  if (text.length <= max) return text;
-  return `${text.slice(0, max)}\n…[checkpoint feedback truncated: ${text.length - max} chars dropped]`;
-}
-
-async function emitAbort(ctx: ModeContext, reason: string): Promise<MoxxyEvent> {
-  return ctx.emit({
-    type: 'abort',
-    sessionId: ctx.sessionId,
-    turnId: ctx.turnId,
-    source: 'system',
-    reason,
-  });
-}
-
-async function emitError(
-  ctx: ModeContext,
-  kind: 'retryable' | 'fatal',
-  message: string,
-): Promise<MoxxyEvent> {
-  return ctx.emit({
-    type: 'error',
-    sessionId: ctx.sessionId,
-    turnId: ctx.turnId,
-    source: 'system',
-    kind,
-    message,
-  });
-}
-
-async function emitCheckpointEvent(
-  ctx: ModeContext,
-  subtype: string,
-  payload: unknown,
-): Promise<MoxxyEvent> {
-  return ctx.emit({
-    type: 'plugin_event',
-    sessionId: ctx.sessionId,
-    turnId: ctx.turnId,
-    source: 'system',
-    pluginId: CHECKPOINT_EVENT_PLUGIN_ID,
-    subtype,
-    payload,
-  });
-}

package/src/mode.ts

@@ -8,6 +8,7 @@ import type { EventLogReader } from './log.js';
 import type { PermissionResolver } from './permission.js';
 import type { LLMProvider, ReasoningEffort } from './provider.js';
 import type { LoopGuardSettings } from './mode/stuck-loop.js';
+import type { QuestionAskOptions, QuestionItem, QuestionOutcome } from './question.js';
 import type { Skill } from './skill.js';
 import type { SubagentSpawner } from './subagent.js';
 import type { ToolDef } from './tool.js';
@@ -89,6 +90,13 @@ export interface ModeContext {
   readonly systemPrompt?: string;
   readonly provider: LLMProvider;
   readonly tools: ToolRegistry;
+  /**
+   * Every tool of the session, in any mode (`tools` is this turn's mode's,
+   * plus any it adds for itself). An agent connection lists these to the
+   * vendor agent, which reads its tool list once, and refuses a call to one
+   * this mode does not offer.
+   */
+  readonly allTools?: ToolRegistry;
   readonly skills: SkillRegistry;
   readonly log: EventLogReader;
   readonly compactor: CompactorDef | null;
@@ -125,6 +133,11 @@ export interface ModeContext {
    * picked the default option, or fail closed depending on the strategy.
    */
   readonly approval?: ApprovalResolver;
+  /**
+   * Ask the person a Question in this turn (the conversation's Questions).
+   * Absent where nobody can be asked (subagents, synthetic test contexts).
+   */
+  readonly ask?: (questions: ReadonlyArray<QuestionItem>, opts?: QuestionAskOptions) => Promise<QuestionOutcome>;
   readonly hooks: HookDispatcher;
   readonly pluginHost: PluginHostHandle;
   /** Inter-plugin service registry (mirrors {@link AppContext.services}). */
@@ -246,14 +259,13 @@ export interface ModeDef {
   readonly badge?: ModeBadge;
   /**
    * Marks a "special" mode — one the user does NOT pick from `/mode`. Set this
-   * and the mode is, uniformly across every surface (TUI, mobile, desktop):
+   * and the mode is, uniformly across every surface (TUI, desktop):
    *   - **hidden** from every mode list / picker (presence), and
    *   - **refused** by the normal mode-switch by name (execution) — it can only
    *     be entered through its own invocation (a slash command, a spawned
    *     agent's `MOXXY_MODE`, …) via the raw registry `setActive`.
    * The mode stays registered + runnable; it's just never *offered* or
-   * name-switched. Extensible: any number of special modes (collaborative today,
-   * more later) opt in the same way. See {@link isSelectableMode}.
+   * name-switched. Extensible: any number of special modes opt in the same way. See {@link isSelectableMode}.
    */
   readonly special?: ModeSpecial;
   /**
@@ -277,16 +289,16 @@ export interface ModeDef {
 /** Descriptor for a {@link ModeDef.special} mode — see that field. */
 export interface ModeSpecial {
   /**
-   * Human-facing entry point that enters this mode, e.g. `'collab'` (the
-   * `/collab` command). Surfaced when the user tries to pick/switch it ("entered
-   * via /collab") so the UI can point at the right action.
+   * Human-facing entry point that enters this mode, e.g. `'goal'` (the
+   * `/goal` command). Surfaced when the user tries to pick/switch it ("entered
+   * via /goal") so the UI can point at the right action.
    */
   readonly invokedBy?: string;
 }
 
 /**
  * Whether a mode is user-selectable — i.e. NOT a {@link ModeDef.special} mode.
- * The single predicate every surface (TUI/mobile/desktop mode lists + the
+ * The single predicate every surface (TUI/desktop mode lists + the
  * by-name mode-switch) uses to filter/refuse special modes uniformly. The
  * parameter is intentionally loose (`{ special? }`) so it also applies to the
  * minimal `{ name }` rows the swap-UI registries expose — non-mode defs simply

package/src/npm-registry.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fetchNpmLatest as fetchLatest } from './npm-registry.js';
+
+/** A fetch stub returning a JSON body with the given status. */
+function jsonResponse(status: number, body: unknown): typeof fetch {
+  return vi.fn(async () => ({
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  })) as unknown as typeof fetch;
+}
+
+describe('fetchNpmLatest', () => {
+  it('returns the version string for a 200 with {version}', async () => {
+    const fetchImpl = jsonResponse(200, { version: '1.2.3' });
+    await expect(fetchLatest('@moxxy/cli', { fetchImpl })).resolves.toBe('1.2.3');
+  });
+
+  it('returns null for a 200 whose body has no string version', async () => {
+    await expect(fetchLatest('@moxxy/cli', { fetchImpl: jsonResponse(200, {}) })).resolves.toBeNull();
+    await expect(
+      fetchLatest('@moxxy/cli', { fetchImpl: jsonResponse(200, { version: 42 }) }),
+    ).resolves.toBeNull();
+  });
+
+  it('rejects non-semver and prerelease dist tags before they reach the cache', async () => {
+    await expect(
+      fetchLatest('@moxxy/cli', { fetchImpl: jsonResponse(200, { version: '../../payload' }) }),
+    ).resolves.toBeNull();
+    await expect(
+      fetchLatest('@moxxy/cli', { fetchImpl: jsonResponse(200, { version: '1.2.3-beta.1' }) }),
+    ).resolves.toBeNull();
+  });
+
+  it('returns null for a 404 (and never reads the body)', async () => {
+    const json = vi.fn(async () => ({ version: 'should-not-be-read' }));
+    const fetchImpl = vi.fn(async () => ({ ok: false, status: 404, json })) as unknown as typeof fetch;
+    await expect(fetchLatest('@moxxy/cli', { fetchImpl })).resolves.toBeNull();
+    expect(json).not.toHaveBeenCalled();
+  });
+
+  it('returns null for a 500', async () => {
+    await expect(
+      fetchLatest('@moxxy/cli', { fetchImpl: jsonResponse(500, {}) }),
+    ).resolves.toBeNull();
+  });
+
+  it('returns null when the fetch implementation rejects (offline)', async () => {
+    const fetchImpl = vi.fn(async () => {
+      throw new Error('network down');
+    }) as unknown as typeof fetch;
+    await expect(fetchLatest('@moxxy/cli', { fetchImpl })).resolves.toBeNull();
+  });
+
+  it('encodes the package name so a hostile pkg cannot escape the registry path', async () => {
+    let seenUrl = '';
+    const fetchImpl = vi.fn(async (url: string) => {
+      seenUrl = url;
+      return { ok: true, status: 200, json: async () => ({ version: '1.0.0' }) };
+    }) as unknown as typeof fetch;
+    await fetchLatest('@moxxy/cli', { fetchImpl });
+    expect(seenUrl).toBe('https://registry.npmjs.org/%40moxxy%2Fcli/latest');
+
+    // A name containing traversal / a host segment must stay inside the path:
+    // encodeURIComponent escapes the separators (`/` → %2F, npm's own scoped-
+    // package encoding) and the query (`?` → %3F), so the hostile name becomes a
+    // single inert path segment. Bare dots are harmless — what must NOT survive
+    // is an unescaped `../` traversal or a raw `?` query injection.
+    await fetchLatest('../../evil?x=1', { fetchImpl });
+    expect(seenUrl).toBe('https://registry.npmjs.org/..%2F..%2Fevil%3Fx%3D1/latest');
+    expect(seenUrl.startsWith('https://registry.npmjs.org/')).toBe(true);
+    expect(seenUrl.endsWith('/latest')).toBe(true);
+    expect(seenUrl).not.toContain('../');
+    expect(seenUrl).not.toContain('?x=1');
+    expect(seenUrl).toContain('%2F');
+  });
+
+  it('aborts and resolves null when the request outlives the timeout', async () => {
+    let abortSeen = false;
+    // A fetch that never resolves on its own — it only settles when the
+    // AbortController fires, proving the timeout path clears nothing it
+    // shouldn't and returns null fail-soft.
+    const fetchImpl = vi.fn((_url: string, init?: { signal?: AbortSignal }) => {
+      return new Promise((_resolve, reject) => {
+        init?.signal?.addEventListener('abort', () => {
+          abortSeen = true;
+          reject(new Error('aborted'));
+        });
+      });
+    }) as unknown as typeof fetch;
+
+    await expect(fetchLatest('@moxxy/cli', { fetchImpl, timeoutMs: 1 })).resolves.toBeNull();
+    expect(abortSeen).toBe(true);
+  });
+});

package/src/npm-registry.ts

@@ -0,0 +1,57 @@
+/**
+ * Ask the npm registry what version a package's `latest` dist-tag points at.
+ * Pure transport over global `fetch` — no `npm` dependency, no child process —
+ * so `moxxy update`, the TUI's "new version" banner and the agent CLI checks
+ * share one cheap call.
+ *
+ * Fail-soft by contract: every error (offline, timeout, 404, malformed body)
+ * resolves to `null`, never throws. A version check must never break a caller.
+ */
+
+const REGISTRY = 'https://registry.npmjs.org';
+const DEFAULT_TIMEOUT_MS = 4000;
+const STABLE_SEMVER_RE = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+
+function normalizeStableSemver(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const match = STABLE_SEMVER_RE.exec(value);
+  if (!match) return null;
+  const [, major, minor, patch] = match;
+  if (major === undefined || minor === undefined || patch === undefined) return null;
+  return `${Number(major)}.${Number(minor)}.${Number(patch)}`;
+}
+
+export interface FetchNpmLatestOptions {
+  /** Override the fetch implementation (tests inject a stub). */
+  fetchImpl?: typeof fetch;
+  /** Abort the request after this many ms (default 4000). */
+  timeoutMs?: number;
+}
+
+/**
+ * The version under the `latest` dist-tag for `pkg`, or `null` if it can't be
+ * resolved. Uses the per-tag manifest endpoint
+ * (`/<pkg>/latest`) so we transfer a tiny document, not the full packument.
+ */
+export async function fetchNpmLatest(pkg: string, opts: FetchNpmLatestOptions = {}): Promise<string | null> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  // Encode the whole package name (incl. the scope slash) so an arbitrary or
+  // attacker-influenced `pkg` can't inject path traversal / a query string /
+  // another host segment into the registry URL. npm accepts `@scope%2Fname`.
+  const url = `${REGISTRY}/${encodeURIComponent(pkg)}/latest`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  try {
+    const res = await fetchImpl(url, {
+      signal: controller.signal,
+      headers: { accept: 'application/json' },
+    });
+    if (!res.ok) return null;
+    const json = (await res.json()) as { version?: unknown };
+    return normalizeStableSemver(json.version);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/package-root.test.ts

@@ -21,7 +21,7 @@ describe('@moxxy/sdk package root', () => {
   it('exports requirement types through package root declarations', async () => {
     const requirement: import('@moxxy/sdk').MoxxyRequirement = {
       kind: 'runtime',
-      name: 'auth:provider:openai-codex',
+      name: 'auth:provider:codex-agent',
       state: 'ready',
     };
     const check: import('@moxxy/sdk').RequirementCheck = {
@@ -35,7 +35,7 @@ describe('@moxxy/sdk package root', () => {
       ],
     };
 
-    expect(check.issues[0]?.requirement.name).toBe('auth:provider:openai-codex');
+    expect(check.issues[0]?.requirement.name).toBe('auth:provider:codex-agent');
   });
 
   // The main barrel is the browser/RN-safe surface: a value import of any of

package/src/permission.ts

@@ -30,6 +30,13 @@ export interface PermissionRule {
     }>;
   };
   readonly reason?: string;
+  /**
+   * How far an "allow for this session" answer reaches for this tool: only
+   * later calls with the same values under these input keys. For a tool whose
+   * approval grants something by itself (access to an app), where a grant of
+   * the whole tool would let every later, wider request through unasked.
+   */
+  readonly sessionScope?: { readonly inputKeys: ReadonlyArray<string> };
 }
 
 export interface PendingToolCall {
@@ -44,9 +51,32 @@ export interface PendingToolCall {
   readonly requestedAtSeq?: number;
 }
 
+/**
+ * A standing "allow" rule a channel saves to the person's permissions.json:
+ * the whole tool, or with `inputEquals` only calls whose inputs have exactly
+ * these values (`null` for a left-out one).
+ */
+export interface StandingAllowRule {
+  readonly name: string;
+  readonly reason?: string;
+  readonly inputEquals?: Readonly<Record<string, unknown>>;
+}
+
 export interface PermissionContext {
   readonly turnId?: string;
   readonly toolDescription?: string;
+  /**
+   * The rule declared by the tool this turn offers under the call's name. A
+   * mode may offer tools the session registry does not hold (plan mode's
+   * `plan_complete`), so the resolver needs it from the call site.
+   */
+  readonly toolPermission?: PermissionRule;
+  /**
+   * The person answers even while auto-approve is on (standing rules still
+   * decide first): the agent's own setting would have asked them, and they
+   * never chose auto-approve for it.
+   */
+  readonly askPerson?: boolean;
   readonly skillContext?: string;
   readonly sessionId: string;
 }

package/src/process-invocation.test.ts

@@ -272,4 +272,29 @@ describe('spawnExecutableTarget', () => {
 
     expect(JSON.parse(readFileSync(observed, 'utf8'))).toEqual(args.slice(1));
   });
+
+  it("gives a native program the environment its target carries, over the caller's", () => {
+    const child = spawnExecutableTarget(
+      { kind: 'direct', command: process.execPath, env: { MOXXY_TARGET_ENV: 'from target' } },
+      ['-e', 'process.stdout.write(String(process.env.MOXXY_TARGET_ENV))'],
+      { stdio: ['ignore', 'pipe', 'pipe'], env: { MOXXY_TARGET_ENV: 'from caller' } },
+    );
+    let stdout = '';
+    child.stdout?.setEncoding('utf8');
+    child.stdout?.on('data', (chunk: string) => {
+      stdout += chunk;
+    });
+
+    return new Promise<void>((resolve, reject) => {
+      child.once('error', reject);
+      child.once('close', () => {
+        try {
+          expect(stdout).toBe('from target');
+          resolve();
+        } catch (error) {
+          reject(error);
+        }
+      });
+    });
+  });
 });