@vincemakes/kiso-ask-ext 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kiso contributors
+
+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

@@ -0,0 +1,39 @@
+# kiso-ask-ext
+
+The kiso official ask extension: `ask_user` option panels — the model puts
+a real choice to the human, and the answers become durable facts.
+
+One call carries 1-4 questions; each has 2-4 options with optional
+one-line descriptions, single or multi select. The human can also type a
+free-form answer, or decline — and a decline is recorded honestly, naming
+the questions that went unanswered rather than passing for silence.
+
+## How it is loaded
+
+This extension ships **built-in** with the kiso CLI, and only on an
+interactive terminal. The factory takes the panel bridge, so a headless
+session has nothing to pass: its tool table never mentions `ask_user`, and
+a piped run pays no prompt rent for a question nobody could answer.
+
+The same artifact can be installed as a user-level extension (copy
+`dist/kiso-ask.mjs` into `~/.kiso/extensions/`), in which case the
+installing code supplies its own bridge.
+
+## Durability
+
+No new mechanisms. The call is durable as its `tool_call_end`, the answers
+as its `tool_result`, and recovery is the ledger every other tool uses.
+The tool declares `idempotent: true` — asking again is safe, because a
+question has no side effect. An answered call therefore never re-asks,
+including across `kill -9`; an interrupted, unanswered one is surfaced on
+resume for an explicit re-ask.
+
+## Configuration
+
+None.
+
+## Versioning
+
+The version counter is this package's own. It is pinned exactly by the kiso
+CLI it ships with; an extension release reaches CLI users through the next
+CLI release.

package/dist/kiso-ask.mjs

@@ -0,0 +1,141 @@
+/**
+ * kiso official ASK extension (KC3.5) — the model can ask the human a
+ * real question: 1-4 questions per call, 2-4 options each with optional
+ * descriptions, single or multi select, a type-an-answer escape, and an
+ * esc decline that RECORDS what was skipped.
+ *
+ * The rent is paid only where it can be earned. A headless session has
+ * nobody to answer, so it never loads this extension and its tool table
+ * never mentions ask_user — the factory takes the panel bridge (`ui`)
+ * and the CLI passes one ONLY on the TTY path (the subagent role-policy
+ * precedent: a child that cannot answer never asks). Handed no bridge,
+ * the extension still loads and still contributes nothing.
+ *
+ * DURABILITY — zero new mechanisms. The call is durable as its
+ * tool_call_end; the answers are durable as its tool_result; recovery is
+ * the EXISTING ledger. `idempotent: true` is the honest declaration:
+ * asking a question again is safe, because a question has no side
+ * effect. (The round's ① probe pinned what the shipped recovery does
+ * with an interrupted execution regardless of that flag — it asks the
+ * human first, and the CLI's copy says so in the ask's own words.)
+ *
+ * NOT here, on purpose (the round's stop clauses): no partial-answer
+ * durability — a crash mid-panel re-presents the WHOLE call, never a
+ * half-filled form; no "chat about this" hand-off; no timeout, no
+ * countdown, no preview pane.
+ *
+ * Zero runtime dependencies: the schema is data and the panel is the
+ * caller's.
+ */
+
+/** The schema the L3 registry enforces — 1-4 questions, 2-4 options
+ *  each, a header capped at 12 cells (the panel's title row). Every
+ *  bound is real: an invalid shape is REFUSED with ajv's own message,
+ *  never a crash and never a half-rendered panel. */
+const ASK_PARAMETERS = {
+	type: "object",
+	properties: {
+		questions: {
+			type: "array",
+			minItems: 1,
+			maxItems: 4,
+			items: {
+				type: "object",
+				properties: {
+					question: { type: "string", minLength: 1 },
+					header: { type: "string", maxLength: 12 },
+					multiSelect: { type: "boolean" },
+					options: {
+						type: "array",
+						minItems: 2,
+						maxItems: 4,
+						items: {
+							type: "object",
+							properties: {
+								label: { type: "string", minLength: 1 },
+								description: { type: "string" },
+							},
+							required: ["label"],
+							additionalProperties: false,
+						},
+					},
+				},
+				required: ["question", "options"],
+				additionalProperties: false,
+			},
+		},
+	},
+	required: ["questions"],
+	additionalProperties: false,
+};
+
+const DESCRIPTION = [
+	"Ask the human a question and wait for the answer.",
+	"1-4 questions per call; each has 2-4 options with optional one-line descriptions.",
+	"Set multiSelect for questions where several options can be picked together.",
+	"The human may also type a free-form answer, or decline: the result then names",
+	"the questions that went unanswered. Use it when a choice is the human's to make",
+	"(a direction, a trade-off, a preference) — never to confirm work you can verify.",
+].join(" ");
+
+/** The result the model reads — the answers, or the honest decline. The
+ *  panel bridge produces it; this shape is the tool_result's whole
+ *  content, so it is JSON and nothing else. */
+function resultContent(result) {
+	return JSON.stringify(result);
+}
+
+/**
+ * The factory. `ui` is the panel bridge: `{ ask(spec, signal) → Promise<
+ * {answers:[…]} | {declined:[…]} > }`. The CLI builds it over the
+ * editor's panel slot; a test can pass any object with that one method.
+ */
+export default async function createAskExtension(ui) {
+	// TTY gating by construction: no bridge, no tool. The extension still
+	// loads (it stays countable, shadowable, disposable like the others)
+	// and simply has nothing to offer a session that cannot answer.
+	if (ui === undefined || ui === null || typeof ui.ask !== "function") return { name: "ask", tools: [] };
+	return {
+		name: "ask",
+		// The approval chain: ask_user is ALLOWED by this extension, and
+		// nothing else is. Requiring approval to ask a question would put
+		// two panels in front of one decision — "approve asking you
+		// something?" then the question itself — and the second panel can
+		// already be declined, which is the same power the first one
+		// offered. (The chain is deny > ask > allow over the SPEAKING
+		// verdicts, so this allow never overrides a user extension's deny
+		// or plan mode's read-only refusal — the moats keep their teeth.)
+		approvals: [
+			{
+				decide: (call) =>
+					call.name === "ask_user"
+						? { action: "allow", reason: "asking the human is the human's own decision to make" }
+						: { action: "abstain" },
+			},
+		],
+		tools: [
+			{
+				name: "ask_user",
+				description: DESCRIPTION,
+				parameters: ASK_PARAMETERS,
+				// asking again is safe — a question has no side effect
+				idempotent: true,
+				promptSnippet: "ask_user — put a real choice to the human (1-4 questions, 2-4 options each)",
+				promptGuidelines: [
+					"ask when the decision is the human's to make; do not ask what you can check",
+					"one call carries every question you need — not four calls in a row",
+				],
+				execute: async (input, ctx) => {
+					const questions = (input ?? {}).questions ?? [];
+					// The schema already refused an empty list; this guard is
+					// for direct tool use (a test, a bridge under repair).
+					if (questions.length === 0) return { content: "ask_user: no questions", isError: true };
+					const result = await ui.ask({ questions }, ctx?.signal);
+					return { content: resultContent(result), isError: false };
+				},
+			},
+		],
+	};
+}
+
+export { ASK_PARAMETERS };

package/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The published type surface of @vincemakes/kiso-ask-ext: the default
+ * export is the FACTORY, and it takes the PANEL BRIDGE. That parameter is
+ * the TTY gate made structural — a caller with no way to ask a human has
+ * nothing to pass, and the extension it gets back contributes no tool.
+ *
+ * The type imports are compile-time only — the shipped bundle is
+ * self-contained, zero runtime dependencies.
+ */
+import type { KisoExtension } from "@vincemakes/kiso-core";
+import type { AskResult, AskSpec } from "@vincemakes/kiso-tui-cells";
+
+/** The panel bridge the CLI implements over its editor's panel slot. */
+export interface AskUI {
+	ask(spec: AskSpec, signal?: { readonly aborted: boolean }): Promise<AskResult>;
+}
+
+declare const createAskExtension: (ui?: AskUI) => Promise<KisoExtension>;
+export default createAskExtension;
+export declare const ASK_PARAMETERS: Readonly<Record<string, unknown>>;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@vincemakes/kiso-ask-ext",
+  "version": "0.8.0",
+  "description": "kiso official ask extension — ask_user option panels: the model asks the human, the answers are durable facts",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/kiso-ask.mjs",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./dist/kiso-ask.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@vincemakes/kiso-core": "0.8.0",
+    "@types/node": "^26.1.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  }
+}