@pi9/ask 0.2.0 → 0.3.0

package/src/replay.ts

@@ -1,100 +0,0 @@
-import type { SessionEntry, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
-import { Check } from "typebox/value";
-
-import { AskAnswerSchema, AskParamsSchema, AskReplayDetailsSchema } from "./schema.js";
-import { formatAskAnswer } from "./response.js";
-import type { AskAnswer, AskParams, AskReplayDetails, ValidatedAskParams } from "./types.js";
-import { validateAskParams } from "./validation.js";
-
-export const ASK_REPLAY_CUSTOM_TYPE = "ask:reanswer" as const;
-
-export type { AskReplayDetails } from "./types.js";
-
-export type AskReplayMessage = {
-  customType: typeof ASK_REPLAY_CUSTOM_TYPE;
-  content: string;
-  display: false;
-  details: AskReplayDetails;
-};
-
-/** Parse the canonical answer shape used by native results and replay details. */
-export function parseAskAnswer(value: unknown): AskAnswer | undefined {
-  return Check(AskAnswerSchema, value) ? value : undefined;
-}
-
-/** Parse canonical replay details, without validating the containing message. */
-export function parseAskReplayDetails(value: unknown): AskReplayDetails | undefined {
-  return Check(AskReplayDetailsSchema, value) ? value : undefined;
-}
-
-export type AskReplayResolution =
-  | { status: "resolved"; toolCallId: string; params: ValidatedAskParams }
-  | {
-      status: "not-replayable";
-      reason: "no-entry" | "not-assistant" | "not-ask" | "multiple-tool-calls" | "mixed-tools" | "invalid-arguments";
-    };
-
-export function buildAskReplayMessage(toolCallId: string, params: ValidatedAskParams, answer: AskAnswer): AskReplayMessage {
-  return {
-    customType: ASK_REPLAY_CUSTOM_TYPE,
-    content: formatAskAnswer(answer).replaceAll("\n", " · "),
-    display: false,
-    details: {
-      toolCallId,
-      question: params.question,
-      ...(params.context !== undefined ? { context: params.context } : {}),
-      allowMultiple: params.allowMultiple,
-      answer,
-    },
-  };
-}
-
-/** Resolve only the selected leaf, or its immediate parent when Pi created a branch summary. */
-export function resolveAskReplayTarget(
-  event: Pick<SessionTreeEvent, "newLeafId" | "summaryEntry">,
-  getEntry: (id: string) => SessionEntry | undefined | null,
-): AskReplayResolution {
-  if (!event.newLeafId) return rejected("no-entry");
-
-  let entry = getEntry(event.newLeafId);
-  const summary = event.summaryEntry?.id === event.newLeafId
-    ? event.summaryEntry
-    : entry?.type === "branch_summary" ? entry : undefined;
-  if (summary) entry = summary.parentId ? getEntry(summary.parentId) : undefined;
-  if (!entry) return rejected("no-entry");
-
-  let selectedToolCallId: string | undefined;
-  if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolName === "ask") {
-    selectedToolCallId = entry.message.toolCallId;
-    entry = entry.parentId ? getEntry(entry.parentId) : undefined;
-  }
-  if (!entry) return rejected("no-entry");
-  if (entry.type !== "message" || entry.message.role !== "assistant") return rejected("not-assistant");
-
-  const calls = entry.message.content.filter((item) => item.type === "toolCall");
-  const askCalls = calls.filter((call) => call.name === "ask");
-  if (calls.length !== 1) {
-    if (askCalls.length > 0 && askCalls.length < calls.length) return rejected("mixed-tools");
-    if (askCalls.length > 1) return rejected("multiple-tool-calls");
-    return rejected("not-ask");
-  }
-  const call = calls[0];
-  if (call.name !== "ask" || (selectedToolCallId !== undefined && call.id !== selectedToolCallId)) return rejected("not-ask");
-
-  const params = validateStoredArgs(call.arguments);
-  if (!params) return rejected("invalid-arguments");
-  return { status: "resolved", toolCallId: call.id, params };
-}
-
-export function validateStoredArgs(value: unknown): ValidatedAskParams | undefined {
-  if (!Check(AskParamsSchema, value)) return undefined;
-  try {
-    return validateAskParams(value as AskParams);
-  } catch {
-    return undefined;
-  }
-}
-
-function rejected(reason: Exclude<AskReplayResolution, { status: "resolved" }>["reason"]): AskReplayResolution {
-  return { status: "not-replayable", reason };
-}

package/src/response.ts

@@ -1,31 +0,0 @@
-import type { AskAnswer, AskResponse, AskToolDetails } from "./types.js";
-
-export function formatAskAnswer(answer: AskAnswer): string {
-  const lines = answer.selections.map((selection) => {
-    const description = selection.description ? ` — ${selection.description}` : "";
-    const comment = selection.comment ? ` (${selection.comment})` : "";
-    return `Selected: ${selection.label}${description}${comment}`;
-  });
-  if (answer.freeform) lines.push(`Freeform: ${answer.freeform}`);
-  return lines.join("\n") || "No answer provided.";
-}
-
-export function buildAnsweredResponse(question: string, answer: AskAnswer): AskResponse {
-  return buildResponse(formatAskAnswer(answer), { status: "answered", question, answer });
-}
-
-export function buildUnansweredResponse(question: string): AskResponse {
-  return buildResponse("The question timed out without an answer.", { status: "unanswered", question });
-}
-
-export function buildCancelledResponse(question: string): AskResponse {
-  return buildResponse("User cancelled the question.", { status: "cancelled", question });
-}
-
-export function buildUiUnavailableResponse(question: string): AskResponse {
-  return buildResponse("Interactive UI is unavailable.", { status: "ui_unavailable", question });
-}
-
-function buildResponse(text: string, details: AskToolDetails): AskResponse {
-  return { content: [{ type: "text", text }], details };
-}

package/src/schema.ts

@@ -1,43 +0,0 @@
-import { Type } from "typebox";
-
-import { MAX_TIMEOUT_MS } from "./config.js";
-
-export const AskOptionSchema = Type.Object({
-  label: Type.String({ minLength: 1, description: "Short option title; keep distinct across options." }),
-  description: Type.Optional(Type.String({ description: "Brief explanation when the label alone is ambiguous." })),
-  preview: Type.Optional(Type.String({ description: "Markdown shown to the user, e.g. code, plans, or comparisons; not returned in the answer." })),
-}, { additionalProperties: false });
-
-export const AskParamsSchema = Type.Object({
-  question: Type.String({ minLength: 1 }),
-  context: Type.Optional(Type.String({ description: "Optional background shown above the question, e.g. what prompted the ask." })),
-  options: Type.Array(AskOptionSchema, { minItems: 1, description: "Suggested answers." }),
-  allowMultiple: Type.Optional(Type.Boolean({ default: false, description: "Allow selecting multiple options. Defaults to false." })),
-  allowFreeform: Type.Optional(Type.Boolean({ default: true, description: "Allow a typed response. Defaults to true." })),
-  timeout: Type.Optional(Type.Integer({ minimum: 0, maximum: MAX_TIMEOUT_MS, description: "Timeout in ms for answers that would go stale; the call returns unanswered on expiry. Zero disables any default." })),
-}, { additionalProperties: false });
-
-export const AskSelectionSchema = Type.Object({
-  label: Type.String({ minLength: 1 }),
-  description: Type.Optional(Type.String({ minLength: 1 })),
-  comment: Type.Optional(Type.String({ minLength: 1 })),
-}, { additionalProperties: false });
-
-export const AskAnswerSchema = Type.Object({
-  selections: Type.Array(AskSelectionSchema),
-  freeform: Type.Optional(Type.String({ minLength: 1 })),
-}, { additionalProperties: false });
-
-export const AskReplayDetailsSchema = Type.Object({
-  toolCallId: Type.String({ minLength: 1 }),
-  question: Type.String({ minLength: 1 }),
-  context: Type.Optional(Type.String({ minLength: 1 })),
-  allowMultiple: Type.Boolean(),
-  answer: AskAnswerSchema,
-}, { additionalProperties: false });
-
-export const AskAnsweredDetailsSchema = Type.Object({
-  status: Type.Literal("answered"),
-  question: Type.String({ minLength: 1 }),
-  answer: AskAnswerSchema,
-}, { additionalProperties: false });

package/src/types.ts

@@ -1,33 +0,0 @@
-import type { Static } from "typebox";
-
-import type {
-  AskAnswerSchema,
-  AskAnsweredDetailsSchema,
-  AskOptionSchema,
-  AskParamsSchema,
-  AskReplayDetailsSchema,
-  AskSelectionSchema,
-} from "./schema.js";
-
-export type AskOption = Static<typeof AskOptionSchema>;
-export type AskParams = Static<typeof AskParamsSchema>;
-export type AskSelection = Static<typeof AskSelectionSchema>;
-export type AskAnswer = Static<typeof AskAnswerSchema>;
-export type AskReplayDetails = Static<typeof AskReplayDetailsSchema>;
-export type AskAnsweredDetails = Static<typeof AskAnsweredDetailsSchema>;
-
-export type ValidatedAskParams = Omit<AskParams, "allowMultiple" | "allowFreeform"> & {
-  allowMultiple: boolean;
-  allowFreeform: boolean;
-};
-
-export type AskToolDetails =
-  | AskAnsweredDetails
-  | { status: "unanswered"; question: string }
-  | { status: "cancelled"; question: string }
-  | { status: "ui_unavailable"; question: string };
-
-export type AskResponse = {
-  content: Array<{ type: "text"; text: string }>;
-  details: AskToolDetails;
-};

package/src/validation.ts

@@ -1,48 +0,0 @@
-import type { AskOption, AskParams, ValidatedAskParams } from "./types.js";
-
-export function validateAskParams(params: AskParams): ValidatedAskParams {
-  const question = params.question.trim();
-  if (!question) throw new Error("Ask question must not be empty.");
-
-  const context = trimOptional(params.context);
-  const options = params.options.map(normalizeOption);
-  const labels = new Set<string>();
-  for (const option of options) {
-    if (labels.has(option.label)) throw new Error(`Ask options contain duplicate label: ${option.label}.`);
-    labels.add(option.label);
-  }
-
-  const allowFreeform = params.allowFreeform ?? true;
-  if (options.length === 0) throw new Error("Ask needs at least one option.");
-
-  return {
-    question,
-    ...(context === undefined ? {} : { context }),
-    options,
-    allowMultiple: params.allowMultiple ?? false,
-    allowFreeform,
-    ...(params.timeout === undefined ? {} : { timeout: params.timeout }),
-  };
-}
-
-function normalizeOption(option: AskOption): AskOption {
-  const label = option.label.trim();
-  if (!label) throw new Error("Ask option label must not be empty.");
-  const description = trimOptional(option.description);
-  const preview = preserveOptional(option.preview);
-  return {
-    label,
-    ...(description === undefined ? {} : { description }),
-    ...(preview === undefined ? {} : { preview }),
-  };
-}
-
-function trimOptional(value: string | undefined): string | undefined {
-  if (value === undefined) return undefined;
-  const trimmed = value.trim();
-  return trimmed || undefined;
-}
-
-function preserveOptional(value: string | undefined): string | undefined {
-  return value?.trim() ? value : undefined;
-}