@moxxy/sdk 0.44.0 → 0.45.0

package/src/question.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest';
+import type { MoxxyEvent } from './events.js';
+import {
+  QUESTION_ASKED,
+  QUESTION_PLUGIN_ID,
+  QUESTION_RESOLVED,
+  describeQuestionAnswers,
+  openQuestionsFromEvents,
+  questionAnswersProblem,
+  questionRecord,
+  type QuestionItem,
+} from './question.js';
+
+let seq = 0;
+const base = (turnId = 't1') => ({ id: `e${seq}`, seq: seq++, ts: 0, sessionId: 's', turnId }) as const;
+const record = (subtype: string, payload: unknown, turnId?: string): MoxxyEvent =>
+  ({ ...base(turnId), type: 'plugin_event', source: 'system', pluginId: QUESTION_PLUGIN_ID, subtype, payload }) as unknown as MoxxyEvent;
+const prompt = (): MoxxyEvent => ({ ...base(), type: 'user_prompt', source: 'user', text: 'hi' }) as unknown as MoxxyEvent;
+
+const colour: QuestionItem = {
+  id: 'q1',
+  header: 'Colour',
+  question: 'Which colour should the button be?',
+  options: [
+    { id: 'red', label: 'Red' },
+    { id: 'blue', label: 'Blue', description: 'Matches the logo' },
+  ],
+  multiSelect: false,
+  allowOther: true,
+};
+const features: QuestionItem = {
+  id: 'q2',
+  question: 'Which parts should it cover?',
+  options: [
+    { id: 'auth', label: 'Auth' },
+    { id: 'billing', label: 'Billing' },
+  ],
+  multiSelect: true,
+  allowOther: false,
+};
+
+describe('question records in the log', () => {
+  it('reads an asked and a resolved record, and nothing else', () => {
+    expect(questionRecord(record(QUESTION_ASKED, { questionId: 'x', questions: [colour] }))).toEqual({
+      kind: 'asked',
+      questionId: 'x',
+      turnId: 't1',
+      questions: [colour],
+    });
+    expect(questionRecord(record(QUESTION_RESOLVED, { questionId: 'x', answers: { q1: { selected: ['red'] } } }))).toEqual({
+      kind: 'resolved',
+      questionId: 'x',
+      outcome: { kind: 'answered', answers: { q1: { selected: ['red'] } } },
+    });
+    expect(questionRecord(record(QUESTION_RESOLVED, { questionId: 'x', dismissed: 'cancelled' }))).toEqual({
+      kind: 'resolved',
+      questionId: 'x',
+      outcome: { kind: 'dismissed', reason: 'cancelled' },
+    });
+    expect(questionRecord(prompt())).toBeNull();
+    expect(questionRecord(record('other', { questionId: 'x' }))).toBeNull();
+    expect(questionRecord(record(QUESTION_ASKED, { questionId: 'x', questions: 'nope' }))).toBeNull();
+  });
+
+  it('keeps open only the questions nothing has resolved yet, in the order they were asked', () => {
+    const events = [
+      record(QUESTION_ASKED, { questionId: 'a', questions: [colour] }, 't1'),
+      prompt(),
+      record(QUESTION_ASKED, { questionId: 'b', questions: [features] }, 't2'),
+      record(QUESTION_RESOLVED, { questionId: 'a', dismissed: 'cancelled' }),
+      record(QUESTION_ASKED, { questionId: 'c', questions: [colour] }, 't3'),
+    ];
+    expect(openQuestionsFromEvents(events).map((q) => [q.questionId, q.turnId])).toEqual([
+      ['b', 't2'],
+      ['c', 't3'],
+    ]);
+  });
+
+  it('has no open question in a conversation that never asked one', () => {
+    expect(openQuestionsFromEvents([prompt(), prompt()])).toEqual([]);
+  });
+});
+
+describe('checking an answer against its question', () => {
+  const questions = [colour, features];
+
+  it('accepts one choice, an answer of the person own, or several choices where allowed', () => {
+    expect(questionAnswersProblem(questions, { q1: { selected: ['blue'] }, q2: { selected: ['auth', 'billing'] } })).toBeNull();
+    expect(questionAnswersProblem(questions, { q1: { selected: [], other: 'Teal' }, q2: { selected: ['auth'] } })).toBeNull();
+  });
+
+  it('names what is wrong with an answer the question cannot take', () => {
+    expect(questionAnswersProblem(questions, { q1: { selected: ['blue'] } })).toBe('No answer to "Which parts should it cover?".');
+    expect(questionAnswersProblem(questions, { q1: { selected: ['red', 'blue'] }, q2: { selected: ['auth'] } })).toBe(
+      '"Which colour should the button be?" takes one answer.',
+    );
+    expect(questionAnswersProblem(questions, { q1: { selected: ['green'] }, q2: { selected: ['auth'] } })).toBe(
+      '"Which colour should the button be?" has no answer "green".',
+    );
+    expect(questionAnswersProblem(questions, { q1: { selected: ['red'] }, q2: { selected: [], other: 'Logs' } })).toBe(
+      '"Which parts should it cover?" takes only the answers it offers.',
+    );
+    expect(questionAnswersProblem(questions, { q1: { selected: [], other: '   ' }, q2: { selected: ['auth'] } })).toBe(
+      'No answer to "Which colour should the button be?".',
+    );
+    expect(questionAnswersProblem(questions, { q1: { selected: ['red'], other: 'Teal' }, q2: { selected: ['auth'] } })).toBe(
+      '"Which colour should the button be?" takes one answer.',
+    );
+    expect(
+      questionAnswersProblem(questions, { q1: { selected: ['red'] }, q2: { selected: ['auth'] }, q9: { selected: [] } }),
+    ).toBe('There is no question "q9".');
+  });
+});
+
+describe('telling the agent what the person answered', () => {
+  it('quotes each question with the labels chosen and the words typed', () => {
+    expect(
+      describeQuestionAnswers([colour, features], {
+        q1: { selected: [], other: 'Teal' },
+        q2: { selected: ['auth', 'billing'] },
+      }),
+    ).toBe(
+      [
+        'The user answered:',
+        '- "Which colour should the button be?" → their own answer: Teal',
+        '- "Which parts should it cover?" → Auth, Billing',
+      ].join('\n'),
+    );
+  });
+});

package/src/question.ts

@@ -0,0 +1,229 @@
+import { z } from 'zod/v3';
+import type { MoxxyEvent } from './events.js';
+import { asPluginId, type TurnId } from './ids.js';
+import type { QuestionAnswerDisplay } from './tool-display.js';
+
+/**
+ * A Question is the agent asking the person to choose or answer: it blocks no
+ * action and auto-approve never answers it. It belongs to the conversation, not
+ * to one client: asking and resolving are recorded in the event log as
+ * `plugin_event`s, so every surface attached to the session shows the same open
+ * question, and the first answer from any of them closes it everywhere.
+ */
+export const QUESTION_PLUGIN_ID = asPluginId('@moxxy/question');
+export const QUESTION_ASKED = 'question_asked';
+export const QUESTION_RESOLVED = 'question_resolved';
+
+export interface QuestionOption {
+  readonly id: string;
+  readonly label: string;
+  readonly description?: string;
+}
+
+export interface QuestionItem {
+  readonly id: string;
+  /** A short tag for the question, as Claude's AskUserQuestion and Codex send it. */
+  readonly header?: string;
+  readonly question: string;
+  /** Empty when only an answer of the person's own fits. */
+  readonly options: ReadonlyArray<QuestionOption>;
+  readonly multiSelect: boolean;
+  /** Whether the person may answer in their own words instead of an option. */
+  readonly allowOther: boolean;
+}
+
+/** The ids of the options chosen, and the words typed when the question takes them. */
+export interface QuestionAnswer {
+  readonly selected: ReadonlyArray<string>;
+  readonly other?: string;
+}
+
+export type QuestionAnswers = Readonly<Record<string, QuestionAnswer>>;
+
+export type QuestionOutcome =
+  | { readonly kind: 'answered'; readonly answers: QuestionAnswers }
+  /** Closed before anyone answered: the turn waiting on it stopped, or `note` says why else. */
+  | { readonly kind: 'dismissed'; readonly reason: 'cancelled'; readonly note?: QuestionCloseNote }
+  /** No surface that can show a question is attached, so nobody will answer. */
+  | { readonly kind: 'unanswerable' };
+
+/** The agent went on working without the answer, so nothing waits on it any more. */
+export const QUESTION_CLOSED_AGENT_WENT_ON = 'agent-went-on';
+/** The person sent a new message instead of answering. */
+export const QUESTION_CLOSED_NEW_MESSAGE = 'new-message';
+/** Why a question closed unanswered, when it was not the turn stopping. */
+export type QuestionCloseNote = typeof QUESTION_CLOSED_AGENT_WENT_ON | typeof QUESTION_CLOSED_NEW_MESSAGE;
+
+/** The close note `value` names, or undefined for anything else (an abort reason, a note a newer Moxxy wrote). */
+export function questionCloseNote(value: unknown): QuestionCloseNote | undefined {
+  return value === QUESTION_CLOSED_AGENT_WENT_ON || value === QUESTION_CLOSED_NEW_MESSAGE ? value : undefined;
+}
+
+/**
+ * How the asker of a question in a turn may close it before the turn ends:
+ * aborting `signal` closes it unanswered, with the abort reason as its note
+ * when that is a {@link QuestionCloseNote}.
+ */
+export interface QuestionAskOptions {
+  readonly signal?: AbortSignal;
+}
+
+/** Asks the person and waits: answered, stopped with the turn, or nobody attached to answer. */
+export type QuestionAsker = (request: {
+  readonly turnId: TurnId;
+  readonly questions: ReadonlyArray<QuestionItem>;
+  readonly signal: AbortSignal;
+}) => Promise<QuestionOutcome>;
+
+/** The session's side of questions that a surface (desktop, TUI, a channel bot) drives. */
+export interface SessionQuestions {
+  /** Say this surface can show questions and take answers; call the result when it detaches. */
+  attachSurface(): () => void;
+  /** Answer an open question. Rejects when it is no longer open or the answer does not fit it. */
+  answer(questionId: string, answers: QuestionAnswers): Promise<void>;
+}
+
+export const questionOptionSchema = z
+  .object({ id: z.string().min(1), label: z.string().min(1), description: z.string().optional() })
+  .strict();
+
+export const questionItemSchema = z
+  .object({
+    id: z.string().min(1),
+    header: z.string().optional(),
+    question: z.string().min(1),
+    options: z.array(questionOptionSchema),
+    multiSelect: z.boolean(),
+    allowOther: z.boolean(),
+  })
+  .strict()
+  .refine((item) => item.options.length > 0 || item.allowOther, 'A question without options must take an answer of the person own.');
+
+export const questionAnswerSchema = z
+  .object({ selected: z.array(z.string()), other: z.string().optional() })
+  .strict();
+
+export const questionAnswersSchema = z.record(questionAnswerSchema);
+
+const askedSchema = z.object({ questionId: z.string().min(1), questions: z.array(questionItemSchema).min(1) });
+const resolvedSchema = z.union([
+  z.object({ questionId: z.string().min(1), answers: questionAnswersSchema }),
+  // Any note is read, so a record a newer Moxxy wrote still closes its question here.
+  z.object({ questionId: z.string().min(1), dismissed: z.literal('cancelled'), note: z.string().optional() }),
+]);
+
+export type QuestionRecord =
+  | {
+      readonly kind: 'asked';
+      readonly questionId: string;
+      readonly turnId: string;
+      readonly questions: ReadonlyArray<QuestionItem>;
+    }
+  | {
+      readonly kind: 'resolved';
+      readonly questionId: string;
+      readonly outcome: Extract<QuestionOutcome, { kind: 'answered' | 'dismissed' }>;
+    };
+
+function dismissedOutcome(note: QuestionCloseNote | undefined): Extract<QuestionOutcome, { kind: 'dismissed' }> {
+  return note ? { kind: 'dismissed', reason: 'cancelled', note } : { kind: 'dismissed', reason: 'cancelled' };
+}
+
+/** What a question record in the log says, or null when the event is not one. */
+export function questionRecord(event: MoxxyEvent): QuestionRecord | null {
+  if (event.type !== 'plugin_event' || event.pluginId !== QUESTION_PLUGIN_ID) return null;
+  if (event.subtype === QUESTION_ASKED) {
+    const parsed = askedSchema.safeParse(event.payload);
+    if (!parsed.success) return null;
+    return { kind: 'asked', questionId: parsed.data.questionId, turnId: String(event.turnId), questions: parsed.data.questions };
+  }
+  if (event.subtype === QUESTION_RESOLVED) {
+    const parsed = resolvedSchema.safeParse(event.payload);
+    if (!parsed.success) return null;
+    const outcome =
+      'answers' in parsed.data
+        ? ({ kind: 'answered', answers: parsed.data.answers } as const)
+        : dismissedOutcome(questionCloseNote(parsed.data.note));
+    return { kind: 'resolved', questionId: parsed.data.questionId, outcome };
+  }
+  return null;
+}
+
+export interface OpenQuestion {
+  readonly questionId: string;
+  readonly turnId: string;
+  readonly questions: ReadonlyArray<QuestionItem>;
+}
+
+/** The questions asked and not yet resolved, oldest first: a pure fold over the log. */
+export function openQuestionsFromEvents(events: ReadonlyArray<MoxxyEvent>): ReadonlyArray<OpenQuestion> {
+  const open = new Map<string, OpenQuestion>();
+  for (const event of events) {
+    const found = questionRecord(event);
+    if (!found) continue;
+    if (found.kind === 'asked') {
+      open.set(found.questionId, { questionId: found.questionId, turnId: found.turnId, questions: found.questions });
+    } else {
+      open.delete(found.questionId);
+    }
+  }
+  return [...open.values()];
+}
+
+/** Why `answers` cannot answer `questions`, in one line, or null when they can. */
+export function questionAnswersProblem(
+  questions: ReadonlyArray<QuestionItem>,
+  answers: QuestionAnswers,
+): string | null {
+  const known = new Set(questions.map((item) => item.id));
+  const stray = Object.keys(answers).find((id) => !known.has(id));
+  if (stray !== undefined) return `There is no question "${stray}".`;
+
+  for (const item of questions) {
+    const answer = answers[item.id];
+    const other = typedWords(answer);
+    const chosen = answer ? answer.selected.length : 0;
+    if (chosen === 0 && other === '') return `No answer to "${item.question}".`;
+    if (answer === undefined) continue;
+    const offered = new Set(item.options.map((option) => option.id));
+    const unknown = answer.selected.find((id) => !offered.has(id));
+    if (unknown !== undefined) return `"${item.question}" has no answer "${unknown}".`;
+    if (other !== '' && !item.allowOther) return `"${item.question}" takes only the answers it offers.`;
+    if (!item.multiSelect && chosen + (other === '' ? 0 : 1) > 1) return `"${item.question}" takes one answer.`;
+  }
+  return null;
+}
+
+/** The person's answers as the agent reads them: each question quoted with what was chosen. */
+export function describeQuestionAnswers(questions: ReadonlyArray<QuestionItem>, answers: QuestionAnswers): string {
+  const lines = questions.map((item) => {
+    const answer = answers[item.id];
+    const labels = (answer?.selected ?? []).map((id) => item.options.find((option) => option.id === id)?.label ?? id);
+    const other = typedWords(answer);
+    const parts = [...(labels.length > 0 ? [labels.join(', ')] : []), ...(other ? [`their own answer: ${other}`] : [])];
+    return `- "${item.question}" → ${parts.join('; ')}`;
+  });
+  return ['The user answered:', ...lines].join('\n');
+}
+
+/** The answers as the transcript shows them: each question with the labels picked and any words of the person's own. */
+export function questionAnswerDisplay(questions: ReadonlyArray<QuestionItem>, answers: QuestionAnswers): QuestionAnswerDisplay {
+  return {
+    kind: 'question-answer',
+    questions: questions.map((item) => {
+      const answer = answers[item.id];
+      const chosen = (answer?.selected ?? []).map((id) => item.options.find((option) => option.id === id)?.label ?? id);
+      const own = typedWords(answer);
+      return {
+        ...(item.header ? { header: item.header } : {}),
+        question: item.question,
+        chosen,
+        ...(own ? { own } : {}),
+      };
+    }),
+  };
+}
+
+function typedWords(answer: QuestionAnswer | undefined): string {
+  return answer && answer.other !== undefined ? answer.other.trim() : '';
+}

package/src/questions.ts

@@ -0,0 +1,6 @@
+/**
+ * Questions for browser and React Native clients (`@moxxy/sdk/questions`):
+ * the root entry pulls Node built-ins a renderer bundle cannot load.
+ */
+export * from './question.js';
+export * from './question-draft.js';

package/src/resolvers.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { createAllowListResolver, createDeferredPermissionResolver, evaluateToolRule } from './resolvers.js';
+import { alwaysAllowRule, createAllowListResolver, createDeferredPermissionResolver, createSessionGrants, evaluateToolRule } from './resolvers.js';
 import type { PendingToolCall, PermissionRule } from './permission.js';
 
 function call(name: string, input: unknown = {}): PendingToolCall {
@@ -83,3 +83,86 @@ describe('a decision made now', () => {
     expect((await createAllowListResolver(['computer_run']).check(call('computer_run', {}), { sessionId: 's' })).decidedNow).toBe(true);
   });
 });
+
+describe('a plain allow is one call, not a session grant', () => {
+  it('asks again for the same tool after "allow" (one call only)', async () => {
+    let prompts = 0;
+    const resolver = createDeferredPermissionResolver({
+      prompt: async () => {
+        prompts += 1;
+        return { mode: 'allow' };
+      },
+    });
+    const ctx = { sessionId: 's' };
+    await resolver.check(call('computer_click', { app: 'LM Studio' }), ctx);
+    await resolver.check(call('computer_click', { app: 'LM Studio' }), ctx);
+    expect(prompts).toBe(2);
+  });
+
+  it('does not ask again for the same tool after "allow_session"', async () => {
+    let prompts = 0;
+    const resolver = createDeferredPermissionResolver({
+      prompt: async () => {
+        prompts += 1;
+        return { mode: 'allow_session' };
+      },
+    });
+    const ctx = { sessionId: 's' };
+    await resolver.check(call('computer_click', { app: 'LM Studio' }), ctx);
+    await resolver.check(call('computer_click', { app: 'Safari' }), ctx);
+    expect(prompts).toBe(1);
+  });
+});
+
+// computer_request_access grants an app by itself: an answer for Safari must not let Terminal through.
+describe('a tool that narrows its grant to the same request', () => {
+  const narrowed: PermissionRule = { action: 'prompt', sessionScope: { inputKeys: ['apps', 'full_access'] } };
+  const ctx = { sessionId: 's', toolPermission: narrowed };
+
+  it.each(['allow_session', 'allow_always'] as const)('remembers only that request after "%s", in this conversation', async (mode) => {
+    let prompts = 0;
+    const resolver = createDeferredPermissionResolver({
+      prompt: async () => {
+        prompts += 1;
+        return { mode };
+      },
+    });
+
+    await resolver.check(call('grant_access', { apps: ['Safari'], full_access: true, reason: 'a' }), ctx);
+    await resolver.check(call('grant_access', { apps: ['Safari'], full_access: true, reason: 'b' }), ctx);
+    await resolver.check(call('grant_access', { apps: ['Terminal'], full_access: true }), ctx);
+    await resolver.check(call('grant_access', { apps: ['Safari'] }), ctx);
+
+    expect(prompts).toBe(3);
+  });
+
+  it('is remembered the same way by a channel that keeps its own grants', () => {
+    const grants = createSessionGrants();
+    grants.remember(call('grant_access', { apps: ['Safari'], full_access: true }), { mode: 'allow_session' }, ctx);
+
+    expect(grants.covers(call('grant_access', { apps: ['Safari'], full_access: true }))).toBe(true);
+    expect(grants.covers(call('grant_access', { apps: ['Terminal'], full_access: true }))).toBe(false);
+  });
+
+  it('is saved for later conversations as that exact request, a left-out value as null', () => {
+    expect(alwaysAllowRule(call('grant_access', { apps: ['Safari'], reason: 'browse' }), ctx)).toEqual({
+      name: 'grant_access',
+      inputEquals: { apps: ['Safari'], full_access: null },
+    });
+  });
+
+  it('is saved as the whole tool for a tool that does not narrow its grant', () => {
+    expect(alwaysAllowRule(call('Write', { file_path: 'a.ts' }), { sessionId: 's' })).toEqual({ name: 'Write' });
+  });
+});
+
+describe('session grants of a channel', () => {
+  it('cover the whole tool after "allow_session" for a tool that does not narrow it, and nothing after "allow"', () => {
+    const grants = createSessionGrants();
+    grants.remember(call('computer_click', { app: 'Notes' }), { mode: 'allow' }, { sessionId: 's' });
+    expect(grants.covers(call('computer_click', { app: 'Notes' }))).toBe(false);
+
+    grants.remember(call('computer_click', { app: 'Notes' }), { mode: 'allow_session' }, { sessionId: 's' });
+    expect(grants.covers(call('computer_click', { app: 'Mail' }))).toBe(true);
+  });
+});

package/src/resolvers.ts

@@ -4,6 +4,7 @@ import type {
   PermissionDecision,
   PermissionResolver,
   PermissionRule,
+  StandingAllowRule,
 } from './permission.js';
 
 export const autoAllowResolver: PermissionResolver = {
@@ -77,21 +78,12 @@ export function createDeferredPermissionResolver(
   opts: DeferredPermissionResolverOptions,
 ): DeferredPermissionResolver {
   const sessionAllows = opts.sessionAllows ?? new Set<string>();
-  const scopedSessionAllows: Array<{
-    toolName: string;
-    inputKeys: ReadonlyArray<string>;
-    signature: string;
-  }> = [];
+  const grants = createSessionGrants();
   const pending = new Set<(d: PermissionDecision) => void>();
   return {
     name: opts.name ?? 'deferred',
     async check(call, ctx) {
-      const scopedAllowed = scopedSessionAllows.some(
-        (grant) =>
-          grant.toolName === call.name &&
-          grant.signature === scopedGrantKey(call, grant.inputKeys),
-      );
-      if (sessionAllows.has(call.name) || scopedAllowed) {
+      if (sessionAllows.has(call.name) || grants.covers(call)) {
         return { mode: 'allow_session', reason: 'allow_session previously granted' };
       }
       const decision = await new Promise<PermissionDecision>((resolve) => {
@@ -107,22 +99,9 @@ export function createDeferredPermissionResolver(
           },
         );
       });
-      // Unscoped allow_session and allow_always skip future prompts for the
-      // same tool within this resolver instance. A scoped grant above remembers
-      // only the matching consequence. allow_always
-      // additionally signals to the caller (via the decision flag) that
-      // the rule should be persisted to ~/.moxxy/permissions.json — but
-      // that persistence isn't our job; the channel does it when wiring
-      // up the dialog.
-      if (decision.mode === 'allow_session' && decision.sessionScope) {
-        scopedSessionAllows.push({
-          toolName: call.name,
-          inputKeys: decision.sessionScope.inputKeys,
-          signature: scopedGrantKey(call, decision.sessionScope.inputKeys),
-        });
-      } else if (decision.mode === 'allow_session' || decision.mode === 'allow_always') {
-        sessionAllows.add(call.name);
-      }
+      // allow_always also skips later prompts in this conversation; saving it
+      // to ~/.moxxy/permissions.json is the channel's job (see alwaysAllowRule).
+      grants.remember(call, decision, ctx);
       return decision.mode === 'deny' ? decision : { ...decision, decidedNow: true };
     },
     abortAll(reason = 'channel closed') {
@@ -132,6 +111,40 @@ export function createDeferredPermissionResolver(
   };
 }
 
+/** What a conversation's "allow for this session" and "always allow" answers cover. */
+export interface SessionGrants {
+  covers(call: PendingToolCall): boolean;
+  /** Remember an answer: the same request only when the answer or the tool narrows it, else the whole tool. */
+  remember(call: PendingToolCall, decision: PermissionDecision, ctx: PermissionContext): void;
+}
+
+export function createSessionGrants(): SessionGrants {
+  const tools = new Set<string>();
+  const requests: Array<{ readonly inputKeys: ReadonlyArray<string>; readonly key: string }> = [];
+  return {
+    covers: (call) =>
+      tools.has(call.name) || requests.some((grant) => grant.key === scopedGrantKey(call, grant.inputKeys)),
+    remember(call, decision, ctx) {
+      if (decision.mode !== 'allow_session' && decision.mode !== 'allow_always') return;
+      const scope = decision.sessionScope ?? ctx.toolPermission?.sessionScope;
+      if (scope) requests.push({ inputKeys: scope.inputKeys, key: scopedGrantKey(call, scope.inputKeys) });
+      else tools.add(call.name);
+    },
+  };
+}
+
+/**
+ * The rule an "Always allow" answer saves: the whole tool, or, for a tool that
+ * narrows its grant to the same request, exactly that request, so a later
+ * conversation is not let through for something nobody approved.
+ */
+export function alwaysAllowRule(call: PendingToolCall, ctx: PermissionContext): StandingAllowRule {
+  const keys = ctx.toolPermission?.sessionScope?.inputKeys;
+  if (!keys) return { name: call.name };
+  const input = isRecord(call.input) ? call.input : {};
+  return { name: call.name, inputEquals: Object.fromEntries(keys.map((key) => [key, input[key] ?? null])) };
+}
+
 function scopedGrantKey(call: PendingToolCall, inputKeys?: ReadonlyArray<string>): string {
   const input = isRecord(call.input) ? call.input : {};
   const keys = inputKeys ?? Object.keys(input).sort();

package/src/schemas.test.ts

@@ -40,6 +40,11 @@ describe('skillFrontmatterSchema', () => {
   it('rejects empty description', () => {
     expect(() => skillFrontmatterSchema.parse({ name: 'x', description: '' })).toThrow();
   });
+
+  it('accepts a description up to 1024 chars, the Agent Skills limit third-party skills are written to', () => {
+    expect(skillFrontmatterSchema.parse({ name: 'x', description: 'd'.repeat(1024) }).description).toHaveLength(1024);
+    expect(() => skillFrontmatterSchema.parse({ name: 'x', description: 'd'.repeat(1025) })).toThrow();
+  });
 });
 
 describe('pluginManifestSchema', () => {

package/src/schemas.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z } from 'zod/v3';
 
 const pluginKindSchema = z.enum([
   'tools',
@@ -63,7 +63,8 @@ export const skillScheduleSchema = z
 
 export const skillFrontmatterSchema = z.object({
   name: z.string().min(1).max(120).regex(/^[a-z0-9][a-z0-9-]*$/, 'name must be slug-like'),
-  description: z.string().min(1).max(240),
+  // 1024 is the Agent Skills limit; installers like `npx skills` ship skills written to it.
+  description: z.string().min(1).max(1024),
   triggers: z.array(z.string().min(1)).optional(),
   'allowed-tools': z.array(z.string().min(1)).optional(),
   aliases: z.array(z.string().regex(/^[a-z0-9][a-z0-9_-]*$/, 'alias must be slug-like')).optional(),

package/src/server.ts

@@ -47,6 +47,9 @@ export { utf8Locale } from './locale.js';
 // options type is re-exported from the main barrel like other erased types.
 export { CrossProcessFireLock } from './cross-process-lock.js';
 export { readRequestBody, bearerTokenMatches } from './http-utils.js';
+export { fetchNpmLatest, type FetchNpmLatestOptions } from './npm-registry.js';
+// Stop a child and everything it started (process group / taskkill /T).
+export { killTree } from './process-tree.js';
 // Dedicated-channel run-status file: a channel publishes readiness + its public
 // ingest URL so the desktop "Channels" supervisor can observe it out-of-process
 // (node:fs). The `ChannelRunStatus` *type* rides the main barrel like the others.

package/src/session-like.ts

@@ -3,8 +3,9 @@ import type { SessionId, TurnId } from './ids.js';
 import type { CapabilitySpec } from './isolation.js';
 import type { EventLogReader } from './log.js';
 import type { ApprovalResolver, ModeBadge } from './mode.js';
+import type { SessionQuestions } from './question.js';
 import type { PermissionResolver } from './permission.js';
-import type { ModelDescriptor, ProviderKeyValidation, ReasoningEffort } from './provider.js';
+import type { AgentBackgroundWork, AgentScheduledWakeup, AgentCliReport, ModelDescriptor, ProviderKeyValidation, ReasoningEffort } from './provider.js';
 import type { PluginSetupSpec } from './schemas.js';
 import type { ToolIcon } from './tool-icon.js';
 import type { ToolCompactPresentation } from './tool.js';
@@ -63,10 +64,17 @@ export type ProviderAuthKind = 'api-key' | 'oauth';
 export interface ProviderInfo {
   readonly name: string;
   readonly models: ReadonlyArray<ModelDescriptor>;
+  /** The light model a new conversation starts on while the person chose no
+   *  default (see `startingModel`); absent when the provider names none. */
+  readonly starterModel?: string;
   /** 'oauth' when the provider declares an oauth login on its plugin
    *  definition, 'api-key' otherwise. Defaults to 'api-key' for
    *  providers that don't declare. */
   readonly authKind: ProviderAuthKind;
+  /** For an agent connection, the agent's name as the person knows it ("Codex"). */
+  readonly agentName?: string;
+  /** For an agent connection, the last check of its CLI; absent until the first check ends, and from older runners. */
+  readonly agentCli?: AgentCliReport;
   /** True when the provider's plugin can list its models live (e.g.
    *  via /v1/models). Lets the desktop's model picker show a
    *  "Fetch live" affordance only where it makes sense. */
@@ -175,6 +183,10 @@ export interface SessionInfo {
   /** Turns running now, whichever client (or in-process channel) started them.
    *  Reported by a runner to its clients; absent from runners that predate it. */
   readonly runningTurns?: ReadonlyArray<string>;
+  /** What the conversation's agent runs in the background now; absent from runners that predate it. */
+  readonly backgroundWork?: ReadonlyArray<AgentBackgroundWork>;
+  /** When the conversation's agent set itself to come back by itself; absent from runners that predate it. */
+  readonly scheduledWakeups?: ReadonlyArray<AgentScheduledWakeup>;
 }
 
 /**
@@ -558,6 +570,12 @@ export interface SessionLike {
   pluginsAdmin?: PluginsAdminView;
   /** Provider onboarding slice backing in-channel connect (key entry / OAuth). */
   providerSetup?: ProviderSetupView;
+  /**
+   * Questions the agent asks the person. Open questions are read from the log
+   * with `openQuestionsFromEvents`; this slice attaches a surface and answers.
+   * Optional capability per the seam convention: callers MUST guard.
+   */
+  readonly questions?: SessionQuestions;
   /**
    * Re-read the merged config from disk and live-apply the safe subset —
    * backs the TUI /settings panel's write-then-apply. Structurally matches

package/src/skill-mentions.test.ts

@@ -5,7 +5,7 @@ import type { Skill, SkillFrontmatter } from './skill.js';
 import { insertMention, mentionedSkills, mentionOptions, mentionQueryAt, skillAttachment, withoutTools } from './skill-mentions.js';
 import type { SkillInfo } from './session-like.js';
 import { defineTool } from './define.js';
-import { z } from 'zod';
+import { z } from 'zod/v3';
 
 const skill = (frontmatter: Omit<SkillFrontmatter, 'description'>, body = 'Do it on the desktop.'): Skill => ({
   id: asSkillId(`plugin/${frontmatter.name}`),