[Upstream sync] K-Dense-AI/scientific-agent-skills (github) — 9 added, 27 modified #43
+63
-25
@@ -2,9 +2,9 @@
|
||||
title: "pi-interview Package"
|
||||
task: ""
|
||||
lineage_type: import
|
||||
upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/pi-agent/references/pi-interview.md
|
||||
upstream_sha: 9c9bd2e9
|
||||
imported_at: 2026-06-27
|
||||
upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/b2a92ba0/skills/pi-agent/references/pi-interview.md
|
||||
upstream_sha: b2a92ba0
|
||||
imported_at: 2026-08-14
|
||||
prompt_class: prompt
|
||||
upstream_changes: accepted
|
||||
author: upstream
|
||||
@@ -15,25 +15,31 @@ validated: false
|
||||
|
||||
Source: https://pi.dev/packages/pi-interview
|
||||
|
||||
Interactive interview form extension: the agent collects structured user responses through forms with single/multi-select, text input, image upload, and info panels, plus rich media (code, diffs, Markdown, images, Chart.js charts, Mermaid diagrams, tables, HTML). Requires pi-agent v0.35.0+.
|
||||
Interactive interview forms: the agent collects structured user responses through a form with single/multi-select, text input, image upload, and info panels, plus rich media (code, diffs, Markdown, images, Chart.js charts, Mermaid diagrams, tables, HTML).
|
||||
|
||||
```bash
|
||||
pi install npm:pi-interview
|
||||
pi install npm:glimpseui # optional: native macOS windows (browser fallback otherwise)
|
||||
pi install npm:glimpseui # optional: native macOS window; browser fallback otherwise
|
||||
```
|
||||
|
||||
## Invocation
|
||||
Requires Pi v0.82.1 or later. Restart Pi after installing.
|
||||
|
||||
Agents call the tool directly:
|
||||
## Invocation
|
||||
|
||||
```javascript
|
||||
await interview({
|
||||
questions: '/path/to/questions.json',
|
||||
timeout: 600, // optional, seconds
|
||||
timeout: 600, // optional, seconds (default 600)
|
||||
verbose: false // optional, debug logging
|
||||
});
|
||||
```
|
||||
|
||||
Lifecycle: the tool starts a local server and opens a Glimpse window (macOS), an Orca tab, or a browser tab → the user answers at their own pace with auto-save and timeout reset on any activity → the session ends by Submit (`⌘+Enter`), timeout (warning overlay with an option to stay), or Escape twice → the window closes and the agent receives responses, or `null` if cancelled.
|
||||
|
||||
Remote and Moshi sessions: when the session looks remote (ssh/mosh env, or an active remote login on the host), the tool skips or supplements the local window and prints the form URL with access hints — a Moshi tip when the moshi-hook gateway is running (tap the preview button in the terminal title bar and pick the interview server), and an exact `ssh -L` command for plain SSH (mosh cannot forward ports). The server binds low ports (8377+, scanning forward on collision) and answers tokenless loopback opens with a landing page that hops to the form, so Moshi's browser preview reaches it in one tap. Requests with a non-loopback `Host` header are rejected.
|
||||
|
||||
With multiple concurrent interviews, only the first auto-opens; the rest are queued and surfaced as URLs in tool output, plus a top-right toast with a dropdown to open queued sessions. Submitting the active interview redirects the window to the next queued one. A status bar shows project path, git branch, and session ID.
|
||||
|
||||
## Question Schema
|
||||
|
||||
```json
|
||||
@@ -41,10 +47,15 @@ await interview({
|
||||
"title": "Project Setup",
|
||||
"description": "Review my suggestions and adjust as needed.",
|
||||
"questions": [
|
||||
{ "id": "context", "type": "info", "question": "Architecture context", "context": "This project needs SSR and edge deployment support." },
|
||||
{ "id": "context", "type": "info", "question": "Architecture context",
|
||||
"context": "This project needs SSR and edge deployment support." },
|
||||
{ "id": "framework", "type": "single", "question": "Which framework?",
|
||||
"options": ["React", "Vue", "Svelte"],
|
||||
"recommended": "React", "conviction": "strong", "weight": "critical" }
|
||||
"recommended": "React", "conviction": "strong", "weight": "critical" },
|
||||
{ "id": "features", "type": "multi", "question": "Which features?",
|
||||
"options": ["Auth", "Database", "API"], "recommended": ["Auth", "Database"] },
|
||||
{ "id": "notes", "type": "text", "question": "Additional requirements?" },
|
||||
{ "id": "mockup", "type": "image", "question": "Upload a design mockup" }
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -54,18 +65,24 @@ Question types: `single` (radio), `multi` (checkbox), `text`, `image` (upload),
|
||||
| Field | Purpose |
|
||||
|---|---|
|
||||
| `id`, `type`, `question` | Identifier, type, question text |
|
||||
| `options` | Choices for single/multi; strings or `{ label, content }` objects |
|
||||
| `recommended` | Pre-selected option(s) with badge |
|
||||
| `conviction` | `"strong"` or `"slight"` — controls pre-selection |
|
||||
| `weight` | `"critical"` or `"minor"` — visual prominence |
|
||||
| `context` | Help text |
|
||||
| `content` | Code/diff/Markdown block: `{ source, lang, file, lines, highlights, showSource }`; `lang: "diff"` renders diffs, `lang: "md"` renders Markdown preview |
|
||||
| `media` | Object or array: types `image`, `table`, `chart`, `mermaid`, `html`; each supports `position`: `"above"`/`"below"`/`"side"` and `caption`; tables take `{ headers, rows, highlights }` |
|
||||
| `options` | Choices for single/multi; strings or `{ label, content? }` objects |
|
||||
| `recommended` | Pre-selected option(s) with a "Recommended" badge |
|
||||
| `conviction` | `"strong"` or `"slight"` (slight opts out of pre-selection); requires `recommended` |
|
||||
| `weight` | `"critical"` (prominent card) or `"minor"` (compact card) |
|
||||
| `context` | Help text below the question |
|
||||
| `content` | Code/diff/Markdown block: `{ source, lang, file, lines, highlights, showSource }`; `lang: "diff"` renders a diff, `lang: "md"`/`"markdown"` previews Markdown |
|
||||
| `media` | Object or array of `image`, `table`, `chart`, `mermaid`, `html`; each supports `position` (`"above"`/`"below"`/`"side"`) and `caption`; tables take `{ headers, rows, highlights }` |
|
||||
|
||||
Single/multi questions also support an "Other" custom-text option, per-question image attachments (button or drag & drop), "✦ Generate more" and "↻ Review options" LLM actions, an "Ask about an option" inline assistant panel with prompt chips and provider/model overrides, and an optional per-option clarification field.
|
||||
|
||||
## Response Format
|
||||
|
||||
```typescript
|
||||
interface Response { id: string; value: string | string[]; attachments?: string[]; }
|
||||
interface Response {
|
||||
id: string;
|
||||
value: string | string[];
|
||||
attachments?: string[]; // image paths attached to non-image questions
|
||||
}
|
||||
```
|
||||
|
||||
## Settings
|
||||
@@ -80,19 +97,40 @@ interface Response { id: string; value: string | string[]; attachments?: string[
|
||||
"snapshotDir": "~/.pi/interview-snapshots/",
|
||||
"autoSaveOnSubmit": true,
|
||||
"generateModel": "anthropic/claude-haiku-4-5",
|
||||
"theme": { "mode": "auto", "name": "default", "lightPath": "/path/to/light.css", "darkPath": "/path/to/dark.css", "toggleHotkey": "mod+shift+l" }
|
||||
"launcher": "browser",
|
||||
"browser": "Firefox",
|
||||
"glimpseFloating": false,
|
||||
"theme": {
|
||||
"mode": "auto",
|
||||
"name": "default",
|
||||
"lightPath": "/path/to/light.css",
|
||||
"darkPath": "/path/to/dark.css",
|
||||
"toggleHotkey": "mod+shift+l"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Timeout precedence: function parameter > settings > default 600s. Built-in themes: `default` (monospace) and `tufte` (serif); modes `dark` (default), `light`, `auto`. Custom themes are CSS files overriding variables like `--bg-body`, `--bg-card`, `--accent`, `--error`.
|
||||
Timeout precedence: function parameter > settings > default 600s. A fixed `port` keeps the URL stable across sessions. `generateModel` drives the generate/review option actions, defaulting to the agent's current model then a cheap available model; if an explicitly configured model fails and the session uses a different one, it retries once with the session model. `glimpseFloating` keeps the native macOS window above others (browser fallback unaffected).
|
||||
|
||||
`launcher` chooses where the form opens; omit it for the default (Glimpse on a local macOS session with `glimpseui` installed, otherwise a browser tab):
|
||||
|
||||
- `"glimpse"` — native macOS Glimpse window; requires a local macOS session with `glimpseui`, and reports why the window could not open instead of falling back to a browser.
|
||||
- `"browser"` — browser tab even when Glimpse is installed.
|
||||
- `"orca"` — a browser tab in the current [Orca](https://github.com/stablyai/orca)-managed worktree, or Orca's focused worktree when the cwd is outside one; the tab is focused when that worktree is visible, otherwise staged in its tab bar. Needs `orca` on `PATH`.
|
||||
|
||||
`browser` names the application used for browser tabs (`"Firefox"`, `"Brave Browser"`, …). It applies to `launcher: "browser"` and to an omitted `launcher` when Glimpse is unavailable; it has no effect under `"glimpse"` or `"orca"`.
|
||||
|
||||
Themes: built-ins are `default` (monospace) and `tufte` (serif); modes are `dark` (default), `light`, and `auto` (follows the OS, user override persists in localStorage). Custom themes are CSS files overriding variables such as `--bg-body`, `--bg-card`, `--bg-elevated`, `--bg-selected`, `--fg`, `--fg-muted`, `--accent`, `--border`, `--success`, `--warning`, `--error`, `--focus-ring`.
|
||||
|
||||
## Keyboard
|
||||
|
||||
`↑`/`↓` navigate options, `⌘+←`/`⌘+→` navigate questions (Ctrl off macOS), `Tab` cycles, `Enter`/`Space` selects, `⌘+V` pastes into the focused input, `⌘+Enter` submits, `Esc` shows the exit overlay (twice to quit), `⌘+Shift+L` toggles the theme when enabled.
|
||||
|
||||
## Recovery and Snapshots
|
||||
|
||||
Abandoned/timed-out interviews save to `~/.pi/interview-recovery/{date}_{time}_{project}_{branch}_{sessionId}.json` (auto-deleted after 7 days). Submissions can auto-save snapshots (`index.html` + `images/`) to `~/.pi/interview-snapshots/`. Resume either by passing the recovery JSON or snapshot `index.html` path as `questions`.
|
||||
Abandoned or timed-out interviews save their questions to `~/.pi/interview-recovery/{date}_{time}_{project}_{branch}_{sessionId}.json`, auto-deleted after 7 days. Snapshots (manual Save button, or automatic on submit with `autoSaveOnSubmit`) land in `~/.pi/interview-snapshots/{title}-{project}-{branch}-{timestamp}[-submitted]/` as `index.html` plus an `images/` subfolder. Resume either by passing the recovery JSON or the snapshot `index.html` path as `questions` — the form reopens with answers pre-populated.
|
||||
|
||||
## Keyboard and Limits
|
||||
## Limits
|
||||
|
||||
`↑`/`↓` navigate options, `⌘+←`/`⌘+→` navigate questions (Ctrl on non-macOS), `Tab` cycles, `Enter`/`Space` selects, `⌘+Enter` submits, `Esc` twice quits, `⌘+Shift+L` toggles theme. Auto-saves via localStorage; detects multi-agent queues.
|
||||
|
||||
Image limits: max 12 per submission, 5MB each, 4096×4096 px, PNG/JPG/GIF/WebP.
|
||||
Max 12 images per submission, 5 MB per image, 4096×4096 pixels, types PNG/JPG/GIF/WebP.
|
||||
|
||||
Reference in New Issue
Block a user