@sigrun/ask-user 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-11-05
+### Added
+- The `ask_user_question` argument contract: `AskParamsSchema` (1–4
+  questions, 2–4 options, header ≤ 16 chars, label ≤ 60 chars) plus
+  `prepareAskArguments` for models that stringify the array.
+- `validateAsk`: unique option labels per question, unique headers, the
+  reserved labels `Other` / `Type something.`, and no preview on
+  multi-select questions.
+- `buildCard`: the question card tree — a submit-mode form with one
+  section per question, each holding a required choice labelled with the
+  full question text, the ` (Recommended)` suffix mapping to
+  `recommended: true`, and a free-text "Type something" row on every
+  choice.
+- The `ask_user_question` tool (model-only, `replay: "safe"`): validate,
+  refuse in scheduled job runs, register the waiter, seed the card
+  idempotently per call id, one snapshot read, then wait for the human.
+  Declines come back as results, not errors; a clean shutdown leaves the
+  card pending for the post-restart rerun; any other abort settles it
+  `cancelled` and rethrows the original abort. No timer ever answers.
+- `Waiters`: the callId-keyed registry joining `interactionSettled`
+  events to in-flight waits.
+- `formatResult`: the settled outcome folded into the tool output and
+  `details`.
+- The extension factory: `interactionKinds: ["ask.questions"]`,
+  `interactiveTools: ["ask_user_question"]`, the `interactionSettled`
+  and `harnessShutdown` lifecycle handlers.
+- The prompt section: the asking discipline, rendered only when the
+  run's agent carries `ask_user_question`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @sigrun/ask-user
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Structured questions from the agent for [sigrun](https://github.com/sigrun-ai/sigrun).
+The agent asks through its `ask_user_question` tool; the question card renders
+in the conversation and waits for the user's answers — it never auto-selects
+an answer, and it waits indefinitely.
+
+## Install
+
+Add the extension to `extensions[]` in the sigrun settings file and restart:
+
+```json
+{
+  "extensions": ["@sigrun/ask-user"]
+}
+```
+
+(a git source — `git:host/path[@ref]` — works too; the repo's committed
+`dist/` is what git-source installs load.)
+
+Until `@sigrun/ask-user` is published, install from a local path pointing at
+the BUILT entry — `"/path/to/sigrun-ask-user/dist/index.js"` in
+`extensions[]`.
+
+## What you get
+
+- **The `ask_user_question` tool**: one to four questions per call, each
+  with two to four options, a short header chip, and multi-select
+  where it fits. A label ending in ` (Recommended)` renders with a
+  recommended marker. The card always adds a free-text "Type something"
+  row, so `Other` and `Type something.` are reserved labels the model
+  must not offer. The numeric limits: 1–4 questions per call, 2–4
+  options per question, header ≤ 16 characters, label ≤ 60 characters.
+- **The question card** in the conversation: one section per question,
+  each a required choice, submitted with "Submit answers" — or declined.
+  Questions wait for a human indefinitely; nothing answers on the user's
+  behalf.
+
+## Decline
+
+The user can always decline a question instead of answering. A decline
+does not error the agent — it is a result: the tool returns "declined"
+and the agent continues from what the user says next (reply-to-decline
+is an ordinary conversation message; the tool never second-guesses it).
+
+## Where it is hidden
+
+- **Scheduled job runs**: there is nobody to ask. The tool refuses with
+  a tool error *before* seeding any card, telling the model to escalate
+  instead.
+- **Curator runs and other non-interactive agents**: the extension
+  declares `ask_user_question` an interactive tool, so core withholds it
+  from agents a human never watches.
+
+## Known limits
+
+- The card is declined or answered — there is no timer and no default.
+- One to four questions per call; two to four options per question;
+  headers at most 16 characters; option labels at most 60.
+- A question is bound to its tool call: on a process restart the pending
+  card is re-seeded from the same call id rather than duplicated.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# Third-party notices
+
+## @juicesharp/rpiv-ask-user-question
+
+- <https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question>
+- This extension's prompt guidance text is adapted from
+  `@juicesharp/rpiv-ask-user-question` 2.15.0.
+
+MIT License
+
+Copyright (c) juicesharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/card.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The card shown to the user (spec §7.2): a root `form` bound to
+ * `/values` in submit mode, one `section` per question titled by its
+ * header, each holding exactly one required `choice` named `q1`…`q4`
+ * whose label is the full question text (the header is too short to
+ * carry it). Options are `o1`…`o4`; a ` (Recommended)` suffix maps to
+ * `recommended: true` with the suffix stripped. Every choice carries
+ * the free-text row (`allowOther: {label: "Type something"}`) — the
+ * reserved labels never appear in the model's options. There are no
+ * note fields: the TUI stepper only takes input in a step's first
+ * field, so a second field would be unreachable there.
+ */
+import type { Tree } from "@sigrun/shared/blocks";
+import type { AskParams } from "./schema.js";
+/** The interaction kind the tool seeds with this card as its tree. */
+export declare const ASK_KIND = "ask.questions";
+export declare function buildCard(params: AskParams): Tree;

package/dist/card.js

@@ -0,0 +1,51 @@
+/**
+ * The card shown to the user (spec §7.2): a root `form` bound to
+ * `/values` in submit mode, one `section` per question titled by its
+ * header, each holding exactly one required `choice` named `q1`…`q4`
+ * whose label is the full question text (the header is too short to
+ * carry it). Options are `o1`…`o4`; a ` (Recommended)` suffix maps to
+ * `recommended: true` with the suffix stripped. Every choice carries
+ * the free-text row (`allowOther: {label: "Type something"}`) — the
+ * reserved labels never appear in the model's options. There are no
+ * note fields: the TUI stepper only takes input in a step's first
+ * field, so a second field would be unreachable there.
+ */
+import { RECOMMENDED_SUFFIX } from "./validate.js";
+/** The interaction kind the tool seeds with this card as its tree. */
+export const ASK_KIND = "ask.questions";
+function choiceOption(option, index) {
+    const recommended = option.label.endsWith(RECOMMENDED_SUFFIX);
+    const label = recommended ? option.label.slice(0, -RECOMMENDED_SUFFIX.length) : option.label;
+    return {
+        id: `o${index + 1}`,
+        label,
+        description: option.description,
+        ...(option.preview !== undefined ? { preview: option.preview } : {}),
+        ...(recommended ? { recommended: true } : {}),
+    };
+}
+function questionSection(question, index) {
+    const choice = {
+        type: "choice",
+        name: `q${index + 1}`,
+        label: question.question,
+        required: true,
+        multi: question.multiSelect === true,
+        allowOther: { label: "Type something" },
+        options: question.options.map(choiceOption),
+    };
+    return { type: "section", title: question.header, children: [choice] };
+}
+export function buildCard(params) {
+    return {
+        v: 1,
+        root: {
+            type: "form",
+            id: "ask",
+            bind: "/values",
+            mode: "submit",
+            submitLabel: "Submit answers",
+            children: params.questions.map(questionSection),
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The ask-user extension factory (Task 9): one {@link Waiters} registry
+ * shared by the tool's waits and the `interactionSettled` lifecycle
+ * handler, with `harnessShutdown` flipping the flag the tool's abort
+ * path reads to tell a clean restart from a real cancellation.
+ *
+ * The factory declares ONE parameter so the loader passes the host in
+ * (`factory.length > 0` gates the host argument); a defaulted first
+ * parameter would swallow it instead.
+ */
+import type { SigrunExtensionResult, SigrunHost } from "@sigrun/sigrun/extension";
+/**
+ * The ask-user extension: the agent asks the user structured questions
+ * through `ask_user_question` and waits for the answer — no timer ever
+ * auto-selects an answer; the user answers or declines.
+ * The required host parameter keeps the factory at arity one for the loader.
+ */
+export default function createAskUser(host: SigrunHost): SigrunExtensionResult;

package/dist/index.js

@@ -0,0 +1,39 @@
+/**
+ * The ask-user extension factory (Task 9): one {@link Waiters} registry
+ * shared by the tool's waits and the `interactionSettled` lifecycle
+ * handler, with `harnessShutdown` flipping the flag the tool's abort
+ * path reads to tell a clean restart from a real cancellation.
+ *
+ * The factory declares ONE parameter so the loader passes the host in
+ * (`factory.length > 0` gates the host argument); a defaulted first
+ * parameter would swallow it instead.
+ */
+import { defineExtension } from "@earendil-works/pi-durable";
+import { ASK_KIND } from "./card.js";
+import { askSection } from "./section.js";
+import { createAskTool } from "./tool.js";
+import { Waiters } from "./waiters.js";
+/**
+ * The ask-user extension: the agent asks the user structured questions
+ * through `ask_user_question` and waits for the answer — no timer ever
+ * auto-selects an answer; the user answers or declines.
+ * The required host parameter keeps the factory at arity one for the loader.
+ */
+export default function createAskUser(host) {
+    // ONE registry: the tool's pending waits and the lifecycle handler's
+    // settles must meet in the same map.
+    const waiters = new Waiters();
+    return {
+        extension: defineExtension({
+            name: "ask-user",
+            tools: [createAskTool({ host, waiters })],
+            sections: [askSection],
+        }),
+        interactionKinds: [ASK_KIND],
+        interactiveTools: ["ask_user_question"],
+        interactionSettled: (event) => waiters.settle(event),
+        harnessShutdown: () => {
+            waiters.shuttingDown = true;
+        },
+    };
+}

package/dist/result.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The tool result text (spec §7.5): what the model reads when the wait
+ * ends. An answer is one line per question, `<header>: <answer>`, where
+ * the answer is the selected option LABELS joined `", "` — the model
+ * knows its own labels; the option ids `o1`… would say nothing — with
+ * the free-text answer quoted and marked `(own words)` last. Declines
+ * and cancellations carry their own fixed sentences so the model never
+ * has to guess whether to retry or move on.
+ */
+import type { AskParams } from "./schema.js";
+import type { Settled } from "./waiters.js";
+/** The structured payload the tool result carries as `details`. */
+export type AskDetails = {
+    status: Settled["status"];
+    answers: {
+        question: string;
+        header: string;
+        selected: string[];
+        other?: string;
+    }[];
+    declinedVia?: "button" | "message";
+};
+/** The copy the model reads verbatim. */
+export declare const DECLINED_BUTTON_TEXT = "The user declined to answer.";
+export declare const DECLINED_MESSAGE_TEXT = "The user declined to answer and replied in chat instead; their message follows.";
+export declare const CANCELLED_TEXT = "The question was cancelled before the user answered.";
+export declare function formatResult(params: AskParams, settled: Settled): {
+    output: string;
+    details: AskDetails;
+    isError?: true;
+};

package/dist/result.js

@@ -0,0 +1,74 @@
+/**
+ * The tool result text (spec §7.5): what the model reads when the wait
+ * ends. An answer is one line per question, `<header>: <answer>`, where
+ * the answer is the selected option LABELS joined `", "` — the model
+ * knows its own labels; the option ids `o1`… would say nothing — with
+ * the free-text answer quoted and marked `(own words)` last. Declines
+ * and cancellations carry their own fixed sentences so the model never
+ * has to guess whether to retry or move on.
+ */
+/** The copy the model reads verbatim. */
+export const DECLINED_BUTTON_TEXT = "The user declined to answer.";
+export const DECLINED_MESSAGE_TEXT = "The user declined to answer and replied in chat instead; their message follows.";
+export const CANCELLED_TEXT = "The question was cancelled before the user answered.";
+/** One question's value under `q<n>`: an option id, or ids/other for multi. */
+function answerPart(question, value) {
+    const labels = new Map(question.options.map((option, index) => [`o${index + 1}`, option.label]));
+    const one = (v, into) => {
+        if (typeof v === "string") {
+            const label = labels.get(v);
+            if (label !== undefined)
+                into.selected.push(label);
+        }
+        else if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+            const other = v.other;
+            if (typeof other === "string")
+                into.other = other;
+        }
+    };
+    const part = { selected: [] };
+    if (Array.isArray(value)) {
+        for (const v of value)
+            one(v, part);
+    }
+    else {
+        one(value, part);
+    }
+    return part;
+}
+/** The answer sentence for one question: labels joined, own words last. */
+function answerText(part) {
+    const pieces = [...part.selected];
+    if (part.other !== undefined)
+        pieces.push(`"${part.other}" (own words)`);
+    return pieces.join(", ");
+}
+export function formatResult(params, settled) {
+    if (settled.status === "skipped") {
+        // Decision: a skip without declinedVia reads as the button sentence.
+        // The field is only absent for declines older than the field, and the
+        // chat-reply copy would claim a message follows when none does.
+        return {
+            output: settled.declinedVia === "message" ? DECLINED_MESSAGE_TEXT : DECLINED_BUTTON_TEXT,
+            details: { status: "skipped", answers: [], ...(settled.declinedVia !== undefined ? { declinedVia: settled.declinedVia } : {}) },
+        };
+    }
+    if (settled.status !== "answered") {
+        return {
+            output: CANCELLED_TEXT,
+            details: { status: settled.status, answers: [] },
+            isError: true,
+        };
+    }
+    const answers = params.questions.map((question, index) => {
+        const part = answerPart(question, settled.values[`q${index + 1}`]);
+        return {
+            question: question.question,
+            header: question.header,
+            selected: part.selected,
+            ...(part.other !== undefined ? { other: part.other } : {}),
+        };
+    });
+    const output = answers.map((answer) => `${answer.header}: ${answerText(answer)}`).join("\n");
+    return { output, details: { status: "answered", answers } };
+}

package/dist/schema.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The `ask_user_question` argument shape: the typebox schema the tool
+ * declares, and `prepareAskArguments` for models that stringify the
+ * array. The limits (1–4 questions, 2–4 options, header ≤ 16, label
+ * ≤ 60) are the ones the design keeps from rpiv so prompting habits
+ * carry over (spec §7.1); rules a schema cannot express live in
+ * `validate.ts`.
+ */
+import { Type, type Static } from "@earendil-works/pi-ai";
+export declare const AskOptionSchema: Type.TObject<{
+    label: Type.TString;
+    description: Type.TString;
+    preview: Type.TOptional<Type.TString>;
+}>;
+export declare const AskQuestionSchema: Type.TObject<{
+    question: Type.TString;
+    header: Type.TString;
+    multiSelect: Type.TOptional<Type.TBoolean>;
+    options: Type.TArray<Type.TObject<{
+        label: Type.TString;
+        description: Type.TString;
+        preview: Type.TOptional<Type.TString>;
+    }>>;
+}>;
+export declare const AskParamsSchema: Type.TObject<{
+    questions: Type.TArray<Type.TObject<{
+        question: Type.TString;
+        header: Type.TString;
+        multiSelect: Type.TOptional<Type.TBoolean>;
+        options: Type.TArray<Type.TObject<{
+            label: Type.TString;
+            description: Type.TString;
+            preview: Type.TOptional<Type.TString>;
+        }>>;
+    }>>;
+}>;
+export type AskOption = Static<typeof AskOptionSchema>;
+export type AskQuestion = Static<typeof AskQuestionSchema>;
+export type AskParams = Static<typeof AskParamsSchema>;
+/**
+ * Models occasionally send the array as a JSON string; normalize that to
+ * parsed form. Anything else passes through unchanged (null/undefined throw
+ * here — the tool's own argument validation rejects them upstream as
+ * invalid_arguments). Pure.
+ */
+export declare function prepareAskArguments(args: unknown): AskParams;

package/dist/schema.js

@@ -0,0 +1,36 @@
+/**
+ * The `ask_user_question` argument shape: the typebox schema the tool
+ * declares, and `prepareAskArguments` for models that stringify the
+ * array. The limits (1–4 questions, 2–4 options, header ≤ 16, label
+ * ≤ 60) are the ones the design keeps from rpiv so prompting habits
+ * carry over (spec §7.1); rules a schema cannot express live in
+ * `validate.ts`.
+ */
+import { Type } from "@earendil-works/pi-ai";
+export const AskOptionSchema = Type.Object({
+    label: Type.String({ maxLength: 60, description: "Short option label" }),
+    description: Type.String({ description: "What this option implies" }),
+    preview: Type.Optional(Type.String({ description: "Markdown preview (single-select questions only)" })),
+});
+export const AskQuestionSchema = Type.Object({
+    question: Type.String({ description: "The full question text" }),
+    header: Type.String({ maxLength: 16, description: "Short chip label, at most 16 characters" }),
+    multiSelect: Type.Optional(Type.Boolean({ description: "Allow choosing more than one option" })),
+    options: Type.Array(AskOptionSchema, { minItems: 2, maxItems: 4 }),
+});
+export const AskParamsSchema = Type.Object({
+    questions: Type.Array(AskQuestionSchema, { minItems: 1, maxItems: 4 }),
+});
+/**
+ * Models occasionally send the array as a JSON string; normalize that to
+ * parsed form. Anything else passes through unchanged (null/undefined throw
+ * here — the tool's own argument validation rejects them upstream as
+ * invalid_arguments). Pure.
+ */
+export function prepareAskArguments(args) {
+    if (typeof args.questions === "string") {
+        const raw = args;
+        return { ...raw, questions: JSON.parse(raw.questions) };
+    }
+    return args;
+}

package/dist/section.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The static prompt section: the asking discipline, not the questions.
+ * Question content must never appear here — prompt bytes that change
+ * per call break every cache the provider keeps.
+ */
+export declare const ASK_SECTION_TEXT = "Asking the user: when a decision is genuinely the user's and the answer would change the work, call `ask_user_question` instead of guessing. Don't ask what the conversation or the project already answers. Group related questions into one call (up to 4). Write each option so its consequence is clear, and put the option you recommend first with \" (Recommended)\" at the end of its label. Use `preview` to show concrete artifacts \u2014 a mockup, a code snippet, a config \u2014 when comparing them helps. The user can always answer in their own words or decline; if they decline, continue from what they say next.";
+export declare const askSection: import("@earendil-works/pi-durable").PromptSection<import("@earendil-works/pi-durable").ToolRegistration>;

package/dist/section.js

@@ -0,0 +1,8 @@
+/**
+ * The static prompt section: the asking discipline, not the questions.
+ * Question content must never appear here — prompt bytes that change
+ * per call break every cache the provider keeps.
+ */
+import { section } from "@earendil-works/pi-durable";
+export const ASK_SECTION_TEXT = "Asking the user: when a decision is genuinely the user's and the answer would change the work, call `ask_user_question` instead of guessing. Don't ask what the conversation or the project already answers. Group related questions into one call (up to 4). Write each option so its consequence is clear, and put the option you recommend first with \" (Recommended)\" at the end of its label. Use `preview` to show concrete artifacts — a mockup, a code snippet, a config — when comparing them helps. The user can always answer in their own words or decline; if they decline, continue from what they say next.";
+export const askSection = section("ask-user", (input) => input.agent.tools.some((tool) => tool.name === "ask_user_question") ? ASK_SECTION_TEXT : undefined);

package/dist/tool.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The `ask_user_question` tool (spec §7.3–7.5): validate, seed the
+ * card, wait for a human — no timer anywhere, the user answers or
+ * declines, never a timeout.
+ *
+ * Order (load-bearing):
+ *
+ * 1. `validateAsk` — an uncardable call is a tool error with nothing
+ *    seeded, so the model can fix the call instead of the user
+ *    answering a broken card.
+ * 2. `jobs.isJobRun` — a scheduled job has nobody to ask; error BEFORE
+ *    seeding so no orphan card lingers.
+ * 3. Register the waiter BEFORE seeding: an answer can only commit once
+ *    the record exists, and the waiter is already listening by then.
+ * 4. `seedInteraction` is idempotent per callId — on the `replay:
+ *    "safe"` rerun after a restart, the first-write-wins commit
+ *    re-reads the same PENDING record instead of duplicating the card.
+ * 5. `snapshotInteraction` once after seeding: covers the answer that
+ *    committed before the waiter attached, and the answer given while
+ *    the process was down (the rerun path).
+ * 6. Await the waiter.
+ * 7. On abort: a settled waiter's answer or decline WON the race and
+ *    stands; otherwise a clean shutdown (`waiters.shuttingDown`,
+ *    `harnessShutdown` fires before closeHarness) leaves the record
+ *    PENDING so the rerun re-seeds it, and any other abort settles the
+ *    record `cancelled` — inside try/catch, because a closing session
+ *    rejects the commit and the original abort must still propagate.
+ *
+ * The execute wrapper's finally discards the waiter entry: a throw
+ * BEFORE the await on `pending` (a rejecting seed) never runs
+ * `wait()`'s own finally, and without the discard the entry would
+ * leak past the failed call.
+ */
+import { type ToolRegistration } from "@earendil-works/pi-durable";
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+import { AskParamsSchema } from "./schema.js";
+import { Waiters } from "./waiters.js";
+/** The tool description the model sees. */
+export declare const ASK_TOOL_DESCRIPTION = "Ask the user 1-4 structured questions and wait for the answers. Each question has 2-4 options; the user can also answer in their own words or decline. Use it when a decision belongs to the user and guessing would risk rework.";
+export declare function createAskTool(deps: {
+    host: SigrunHost;
+    waiters: Waiters;
+}): ToolRegistration<typeof AskParamsSchema>;

package/dist/tool.js

@@ -0,0 +1,179 @@
+/**
+ * The `ask_user_question` tool (spec §7.3–7.5): validate, seed the
+ * card, wait for a human — no timer anywhere, the user answers or
+ * declines, never a timeout.
+ *
+ * Order (load-bearing):
+ *
+ * 1. `validateAsk` — an uncardable call is a tool error with nothing
+ *    seeded, so the model can fix the call instead of the user
+ *    answering a broken card.
+ * 2. `jobs.isJobRun` — a scheduled job has nobody to ask; error BEFORE
+ *    seeding so no orphan card lingers.
+ * 3. Register the waiter BEFORE seeding: an answer can only commit once
+ *    the record exists, and the waiter is already listening by then.
+ * 4. `seedInteraction` is idempotent per callId — on the `replay:
+ *    "safe"` rerun after a restart, the first-write-wins commit
+ *    re-reads the same PENDING record instead of duplicating the card.
+ * 5. `snapshotInteraction` once after seeding: covers the answer that
+ *    committed before the waiter attached, and the answer given while
+ *    the process was down (the rerun path).
+ * 6. Await the waiter.
+ * 7. On abort: a settled waiter's answer or decline WON the race and
+ *    stands; otherwise a clean shutdown (`waiters.shuttingDown`,
+ *    `harnessShutdown` fires before closeHarness) leaves the record
+ *    PENDING so the rerun re-seeds it, and any other abort settles the
+ *    record `cancelled` — inside try/catch, because a closing session
+ *    rejects the commit and the original abort must still propagate.
+ *
+ * The execute wrapper's finally discards the waiter entry: a throw
+ * BEFORE the await on `pending` (a rejecting seed) never runs
+ * `wait()`'s own finally, and without the discard the entry would
+ * leak past the failed call.
+ */
+import { withoutAbortSignal } from "@earendil-works/chord/context";
+import { defineTool } from "@earendil-works/pi-durable";
+import { ASK_KIND, buildCard } from "./card.js";
+import { formatResult } from "./result.js";
+import { AskParamsSchema, prepareAskArguments } from "./schema.js";
+import { validateAsk } from "./validate.js";
+/** A stored record folded into the waiter's `Settled` shape. */
+function settledOfRecord(record) {
+    switch (record.status) {
+        case "answered":
+            return { status: "answered", values: { ...(record.answer?.values ?? {}) } };
+        case "skipped":
+            return {
+                status: "skipped",
+                ...(record.declinedVia !== undefined ? { declinedVia: record.declinedVia } : {}),
+            };
+        case "expired":
+        case "cancelled":
+            return { status: record.status };
+        default:
+            throw new Error("pending is not settled");
+    }
+}
+/** The job-run refusal (verbatim; spec §7.5). */
+const JOB_RUN_TEXT = "ask_user_question is not available in scheduled job runs: no one is there to answer. If the escalate tool is available, use it to hand the user the decision instead.";
+/** The tool description the model sees. */
+export const ASK_TOOL_DESCRIPTION = "Ask the user 1-4 structured questions and wait for the answers. Each question has 2-4 options; the user can also answer in their own words or decline. Use it when a decision belongs to the user and guessing would risk rework.";
+/** One sentence, `isError`, no seed. */
+function errorResult(message) {
+    return { output: [{ type: "text", text: message }], isError: true };
+}
+export function createAskTool(deps) {
+    const { host, waiters } = deps;
+    async function executeBody(args, api, context) {
+        /**
+         * The abort path shared by the snapshot read and the wait. The
+         * record is re-read FIRST: a non-pending record means the human's
+         * answer or decline won the race and stands. Only a still-pending
+         * record is settled `cancelled` (when this abort is not a clean
+         * shutdown), so our own settle can never masquerade as the race
+         * winner — and the ORIGINAL abort error is what rethrows.
+         */
+        const onAbort = async (error) => {
+            const before = await host
+                .snapshotInteraction(api.conversationId, api.callId, withoutAbortSignal(context))
+                .catch(() => undefined);
+            if (before !== undefined && before.status !== "pending") {
+                return { settled: settledOfRecord(before) };
+            }
+            if (!waiters.shuttingDown) {
+                try {
+                    await host.settleInteraction(api.conversationId, api.callId, "cancelled", withoutAbortSignal(context));
+                }
+                catch (settleError) {
+                    console.warn("ask_user_question: cancelling the seeded card failed", settleError);
+                }
+            }
+            return { error };
+        };
+        const invalid = validateAsk(args);
+        if (invalid !== null)
+            return errorResult(invalid);
+        if (await host.jobs.isJobRun(api.conversationId, context)) {
+            return errorResult(JOB_RUN_TEXT);
+        }
+        const pending = waiters.wait(api.callId, context);
+        // Mark the waiter observed NOW: a throw before the await below (a
+        // rejecting seed, an aborted snapshot) would otherwise leave its
+        // rejection unhandled at shutdown.
+        void pending.catch(() => undefined);
+        await host.seedInteraction(api.conversationId, {
+            kind: ASK_KIND,
+            callId: api.callId,
+            status: "pending",
+            createdAt: Date.now(),
+            declinable: true,
+            // SAFETY: AskParams is Static<AskParamsSchema> — plain JSON by
+            // construction (validated against the schema by the harness), but
+            // the typebox interface carries no index signature.
+            details: args,
+            body: buildCard(args),
+        }, context);
+        let settled;
+        let terminal = false;
+        let snap;
+        try {
+            snap = await host.snapshotInteraction(api.conversationId, api.callId, context);
+        }
+        catch (error) {
+            const outcome = await onAbort(error);
+            if ("error" in outcome)
+                throw outcome.error;
+            settled = outcome.settled;
+            terminal = true;
+        }
+        if (!terminal && snap !== undefined && snap.status !== "pending") {
+            settled = settledOfRecord(snap);
+            terminal = true;
+        }
+        if (!terminal) {
+            try {
+                settled = await pending;
+            }
+            catch (error) {
+                const outcome = await onAbort(error);
+                if ("error" in outcome)
+                    throw outcome.error;
+                settled = outcome.settled;
+            }
+        }
+        if (settled === undefined)
+            throw new Error("ask_user_question: settled without a settle");
+        const result = formatResult(args, settled);
+        return {
+            output: [{ type: "text", text: result.output }],
+            // SAFETY: AskDetails is built here from schema-typed fields only
+            // (strings/arrays), hence JSON; its interface lacks an index
+            // signature, so it is not structurally a JsonValue.
+            details: result.details,
+            ...(result.isError ? { isError: true } : {}),
+        };
+    }
+    return defineTool({
+        name: "ask_user_question",
+        description: ASK_TOOL_DESCRIPTION,
+        // Model-only: a code-mode script calling this would block a run no
+        // human watches (and its result is never recorded for replay).
+        callers: ["model"],
+        // Safe to rerun after a restart: the callId-keyed seed is idempotent,
+        // and the snapshot read picks up an answer given while down.
+        replay: "safe",
+        parameters: AskParamsSchema,
+        prepareArguments: prepareAskArguments,
+        execute: async (args, api, context) => {
+            try {
+                return await executeBody(args, api, context);
+            }
+            finally {
+                // A throw before the await on `pending` (a rejecting seed, an
+                // aborted snapshot) never runs wait()'s own finally — drop the
+                // entry here so it cannot leak.
+                waiters.discard(api.callId);
+            }
+        },
+    });
+}

package/dist/validate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The validation rules the schema cannot express (spec §7.1):
+ * per-question option-label uniqueness, the reserved free-text labels
+ * (the extension always adds that row itself), no preview on
+ * multi-select questions, and globally unique headers. Each failure is
+ * one actionable sentence — the message is what the model reads, so it
+ * says exactly what to change.
+ */
+import type { AskParams } from "./schema.js";
+/** The suffix a label may carry to mark the recommended option. */
+export declare const RECOMMENDED_SUFFIX = " (Recommended)";
+/**
+ * The first validation failure, or null when the params are card-shaped.
+ * Assumes the schema already holds (`AskParams`); the schema's numeric
+ * limits are not re-checked here.
+ */
+export declare function validateAsk(params: AskParams): string | null;

package/dist/validate.js

@@ -0,0 +1,45 @@
+/**
+ * The validation rules the schema cannot express (spec §7.1):
+ * per-question option-label uniqueness, the reserved free-text labels
+ * (the extension always adds that row itself), no preview on
+ * multi-select questions, and globally unique headers. Each failure is
+ * one actionable sentence — the message is what the model reads, so it
+ * says exactly what to change.
+ */
+/** The suffix a label may carry to mark the recommended option. */
+export const RECOMMENDED_SUFFIX = " (Recommended)";
+/** Labels the card adds itself; offering them as options would duplicate the row. */
+const RESERVED_LABELS = new Set(["Other", "Type something."]);
+/**
+ * The first validation failure, or null when the params are card-shaped.
+ * Assumes the schema already holds (`AskParams`); the schema's numeric
+ * limits are not re-checked here.
+ */
+export function validateAsk(params) {
+    const headers = new Set();
+    for (const [index, question] of params.questions.entries()) {
+        const n = index + 1;
+        if (headers.has(question.header))
+            return "question headers must be unique";
+        headers.add(question.header);
+        const labels = new Set();
+        for (const option of question.options) {
+            // Compare on the rendered label: the recommended suffix is stripped
+            // before the card draws the option, so "A" and "A (Recommended)" are
+            // the same label, and "Other (Recommended)" is still reserved.
+            const label = option.label.endsWith(RECOMMENDED_SUFFIX)
+                ? option.label.slice(0, -RECOMMENDED_SUFFIX.length)
+                : option.label;
+            if (labels.has(label))
+                return `question ${n}: option labels must be unique`;
+            labels.add(label);
+            if (RESERVED_LABELS.has(label)) {
+                return `question ${n}: "${label}" is reserved — the free-text row is added automatically`;
+            }
+            if (question.multiSelect === true && option.preview !== undefined) {
+                return `question ${n}: preview is only allowed on single-select questions`;
+            }
+        }
+    }
+    return null;
+}

package/dist/waiters.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The waiter registry: the `interactionSettled` lifecycle handler
+ * resolves the promise the tool registered under the same callId
+ * (spec §7.4). An event for another kind, or one with no waiter —
+ * replayed history, a card answered while the process was down, a
+ * settle that raced the waiter away — is dropped: the tool re-reads
+ * the record itself via `snapshotInteraction`, so nothing is lost.
+ *
+ * `shuttingDown` is the flag `harnessShutdown` sets BEFORE the harness
+ * closes. The tool's abort path reads it: a wait interrupted with the
+ * flag set is a clean restart, and the record stays PENDING so the
+ * rerun after restart seeds the same card again (spec §7.5); without
+ * the flag the abort is a real cancellation and the record settles
+ * `cancelled`. NO timers: a question never expires on its own (ruling:
+ * the user answers or declines, never a timeout).
+ */
+import type { Context } from "@earendil-works/chord/context";
+import type { JsonValue } from "@earendil-works/chord";
+import type { ExtensionLifecyclePayload } from "@sigrun/sigrun/extension";
+/** The terminal outcome of one wait. */
+export type Settled = {
+    status: "answered";
+    values: Record<string, JsonValue>;
+} | {
+    status: "skipped";
+    declinedVia?: "button" | "message";
+} | {
+    status: "expired" | "cancelled";
+};
+type SettleEvent = ExtensionLifecyclePayload["interactionSettled"];
+/** Fold a lifecycle event into the waiter's `Settled` shape. */
+export declare function settledOf(event: SettleEvent): Settled;
+export declare class Waiters {
+    #private;
+    /** True once the harness shutdown sequence starts; read by the abort path. */
+    shuttingDown: boolean;
+    /**
+     * The promise the tool awaits: resolves on `settle` with the same
+     * callId, rejects when `context` aborts. Register BEFORE seeding the
+     * card — an answer committed between seeding and registration would
+     * otherwise be missed (the tool's snapshot read is the belt to this
+     * suspender).
+     */
+    wait(callId: string, context: Context): Promise<Settled>;
+    /**
+     * Delete the waiter for `callId` outright. Called from the tool's
+     * execute-body finally so a throw BEFORE the await (a rejecting seed)
+     * cannot leak the entry. No identity guard is needed here: a callId
+     * belongs to exactly one in-flight execute, and the only
+     * re-registration under the same callId is the post-restart rerun,
+     * which registers after this execute has finished.
+     */
+    discard(callId: string): void;
+    /** The `interactionSettled` handler: resolves the matching waiter, drops everything else. */
+    settle(event: SettleEvent): void;
+}
+export {};

package/dist/waiters.js

@@ -0,0 +1,88 @@
+/**
+ * The waiter registry: the `interactionSettled` lifecycle handler
+ * resolves the promise the tool registered under the same callId
+ * (spec §7.4). An event for another kind, or one with no waiter —
+ * replayed history, a card answered while the process was down, a
+ * settle that raced the waiter away — is dropped: the tool re-reads
+ * the record itself via `snapshotInteraction`, so nothing is lost.
+ *
+ * `shuttingDown` is the flag `harnessShutdown` sets BEFORE the harness
+ * closes. The tool's abort path reads it: a wait interrupted with the
+ * flag set is a clean restart, and the record stays PENDING so the
+ * rerun after restart seeds the same card again (spec §7.5); without
+ * the flag the abort is a real cancellation and the record settles
+ * `cancelled`. NO timers: a question never expires on its own (ruling:
+ * the user answers or declines, never a timeout).
+ */
+import { awaitWithContext } from "@earendil-works/chord/context";
+import { ASK_KIND } from "./card.js";
+/** Fold a lifecycle event into the waiter's `Settled` shape. */
+export function settledOf(event) {
+    switch (event.status) {
+        case "answered":
+            // The event's `answer` is the record's PLAIN values map (core
+            // event-bus pushes `record.answer.values`); the values are
+            // render-safe card output, hence JsonValue-shaped.
+            return {
+                status: "answered",
+                values: { ...(event.answer ?? {}) },
+            };
+        case "skipped":
+            return {
+                status: "skipped",
+                ...(event.declinedVia !== undefined ? { declinedVia: event.declinedVia } : {}),
+            };
+        case "expired":
+        case "cancelled":
+            return { status: event.status };
+    }
+}
+export class Waiters {
+    /** True once the harness shutdown sequence starts; read by the abort path. */
+    shuttingDown = false;
+    #waiters = new Map();
+    /**
+     * The promise the tool awaits: resolves on `settle` with the same
+     * callId, rejects when `context` aborts. Register BEFORE seeding the
+     * card — an answer committed between seeding and registration would
+     * otherwise be missed (the tool's snapshot read is the belt to this
+     * suspender).
+     */
+    wait(callId, context) {
+        let resolveFn = () => undefined;
+        const promise = new Promise((resolve) => {
+            resolveFn = resolve;
+        });
+        this.#waiters.set(callId, resolveFn);
+        // Drop the map entry when the wait ends for ANY reason — an aborted
+        // wait never sees a settle, and a stale resolver would swallow a
+        // later call's event under a reused callId. Only OUR entry is
+        // removed: settle() deletes on the resolve path, and a re-registered
+        // waiter for the same callId owns its own entry.
+        return awaitWithContext(promise, context).finally(() => {
+            if (this.#waiters.get(callId) === resolveFn)
+                this.#waiters.delete(callId);
+        });
+    }
+    /**
+     * Delete the waiter for `callId` outright. Called from the tool's
+     * execute-body finally so a throw BEFORE the await (a rejecting seed)
+     * cannot leak the entry. No identity guard is needed here: a callId
+     * belongs to exactly one in-flight execute, and the only
+     * re-registration under the same callId is the post-restart rerun,
+     * which registers after this execute has finished.
+     */
+    discard(callId) {
+        this.#waiters.delete(callId);
+    }
+    /** The `interactionSettled` handler: resolves the matching waiter, drops everything else. */
+    settle(event) {
+        if (event.kind !== ASK_KIND)
+            return;
+        const resolve = this.#waiters.get(event.callId);
+        if (resolve === undefined)
+            return;
+        this.#waiters.delete(event.callId);
+        resolve(settledOf(event));
+    }
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@sigrun/ask-user",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Lets the agent ask the user structured questions and wait for the answer",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "test": "node scripts/check-manifest.mjs --expect-name @sigrun/ask-user && vitest run",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@earendil-works/chord": "1.3.0 || 1.4.0",
+    "@earendil-works/pi-ai": "1.3.0 || 1.4.0",
+    "@earendil-works/pi-durable": "1.3.0 || 1.4.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@earendil-works/chord": "1.4.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-durable": "1.4.0",
+    "@sigrun/shared": "file:../sigrun/shared",
+    "@sigrun/sigrun": "file:../sigrun",
+    "@types/node": "^26.6.4",
+    "tsx": "^4.23.15",
+    "typebox": "1.3.27",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "github",
+    "url": "git+https://github.com/sigrun-ai/sigrun-ask-user.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sigrun-ai/sigrun-ask-user/issues"
+  },
+  "homepage": "https://github.com/sigrun-ai/sigrun-ask-user#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}