@researchcomputer/pista 0.1.2

package/README.md

@@ -0,0 +1,110 @@
+# Pista
+
+A full-featured terminal coding agent powered by [`@researchcomputer/agents-sdk`](https://www.npmjs.com/package/@researchcomputer/agents-sdk). Pista provides a rich Ink-based TUI with:
+
+- Live assistant streaming
+- Slash commands
+- Interactive permission prompts and agent questions
+- Custom OpenAI-compatible endpoints
+- Persistent local sessions and memory
+- Transcript scrollback with `PgUp` / `PgDn`
+
+Sessions and memory are stored under `~/.pista/`.
+Preferences are layered: global defaults live under `~/.pista/preferences.json`, and per-project overrides live under `<project>/.pista/preferences.json`.
+The same preferences files can also carry resolved `skills` entries, which are forwarded to the SDK on agent creation.
+
+## Install
+
+```bash
+npm install -g @researchcomputer/pista
+```
+
+## Usage
+
+```bash
+pista
+```
+
+Or pass options:
+
+```bash
+pista --model gpt-4o-mini --cwd .
+```
+
+Rename the agent at startup:
+
+```bash
+pista --name Mochi
+```
+
+Use a custom OpenAI-compatible endpoint:
+
+```bash
+export MY_LLM_KEY=...
+pista \
+  --endpoint https://my-endpoint.example.com/v1 \
+  --model my-model \
+  --api-style chat
+```
+
+## Environment Variables
+
+Set your provider credentials as usual:
+
+```bash
+export OPENAI_API_KEY=...
+```
+
+Optional:
+
+- `PISTA_MODEL`
+- `PISTA_NAME`
+- `PISTA_ENDPOINT`
+- `PISTA_API_STYLE`
+- `PISTA_CWD`
+- `PISTA_SESSION_ID`
+- `PISTA_PERMISSION_MODE`
+- `PISTA_THINKING`
+
+## In-App Commands
+
+- `/help` shows commands
+- `/name` changes the displayed agent name
+- `/model` picks a model or edits the custom model id
+- `/endpoint` edits the OpenAI-compatible base URL
+- `/api` switches between chat and responses API styles
+- `/jump latest|error|tool` moves the transcript to useful checkpoints
+- `/permissions` changes how tool calls are approved
+- `/thinking` changes reasoning intensity
+- `/session new` starts a fresh session
+- `/abort` aborts the current run
+
+Model, endpoint, and API style selections persist across restarts, with project-level preferences overriding global defaults.
+
+## Skills
+
+Resolved skills can be stored in either preferences file:
+
+```json
+{
+  "skills": [
+    {
+      "id": "typescript",
+      "description": "TypeScript house style",
+      "promptSections": [
+        "Prefer explicit return types on exported functions.",
+        "Avoid `any` unless there is no safer boundary type."
+      ]
+    }
+  ]
+}
+```
+
+Skills are layered the same way as other preferences and passed through to the SDK on agent creation.
+
+## Keyboard Shortcuts
+
+- `Enter` sends the current draft
+- `Shift+Enter` or `Ctrl+J` inserts a newline in the composer
+- `Up` / `Down` cycle through recent drafts
+- `PgUp` / `PgDn` scroll the transcript

package/dist/agent-events.js

@@ -0,0 +1,119 @@
+import { stringifyPreview } from './utils.js';
+export function handleAgentEvent(event, controls) {
+    switch (event.type) {
+        case 'agent_start':
+            controls.setRunning(true);
+            controls.setStatus('Starting run');
+            return;
+        case 'agent_end':
+            controls.setRunning(false);
+            controls.setPendingTools([]);
+            controls.setStatus('Idle');
+            return;
+        case 'turn_start':
+            controls.setStatus('Thinking');
+            return;
+        case 'turn_end':
+            controls.setStatus('Synthesizing response');
+            return;
+        case 'message_update':
+            if (event.assistantMessageEvent.type === 'text_delta') {
+                controls.appendLiveAssistantDelta(event.assistantMessageEvent.delta);
+            }
+            if (event.assistantMessageEvent.type === 'thinking_delta') {
+                controls.setStatus('Thinking');
+            }
+            return;
+        case 'message_end':
+            if (event.message.role === 'assistant') {
+                const finalText = summarizeAssistantMessage(event.message);
+                const body = (finalText || controls.getLiveAssistantText()).trim();
+                if (body) {
+                    controls.appendLog('assistant', controls.getAgentName(), body);
+                }
+                controls.clearLiveAssistant();
+            }
+            return;
+        case 'tool_execution_start':
+            controls.setPendingTools((current) => [...current, event.toolName]);
+            controls.setStatus(`Running ${event.toolName}`);
+            controls.appendLog('tool', event.toolName, condensedArgPreview(event.toolName, event.args));
+            return;
+        case 'tool_execution_update':
+            controls.setStatus(`Running ${event.toolName}`);
+            return;
+        case 'tool_execution_end':
+            controls.setPendingTools((current) => {
+                let removed = false;
+                return current.filter((name) => {
+                    if (!removed && name === event.toolName) {
+                        removed = true;
+                        return false;
+                    }
+                    return true;
+                });
+            });
+            controls.setStatus('Thinking');
+            controls.appendLog(event.isError ? 'error' : 'tool', `${event.toolName} ${event.isError ? 'failed' : 'completed'}`, summarizeToolResult(event.result));
+            return;
+        default:
+            return;
+    }
+}
+function summarizeAssistantMessage(message) {
+    if (message.role !== 'assistant')
+        return '';
+    const text = message.content
+        .map((item) => (item.type === 'text' ? item.text : ''))
+        .join('');
+    if (text.trim())
+        return text.trim();
+    if (message.errorMessage)
+        return `[${message.stopReason}] ${message.errorMessage}`;
+    const toolNames = message.content
+        .map((item) => (item.type === 'toolCall' ? item.name : ''))
+        .filter(Boolean);
+    return toolNames.length > 0 ? `[requested tools: ${toolNames.join(', ')}]` : '';
+}
+function summarizeToolResult(result) {
+    if (!result || typeof result !== 'object')
+        return '[no tool output]';
+    const content = result.content;
+    if (Array.isArray(content)) {
+        const text = content
+            .filter((item) => {
+            return Boolean(item) && typeof item === 'object' && item.type === 'text';
+        })
+            .map((item) => item.text)
+            .join('\n')
+            .trim();
+        if (text)
+            return truncate(text, 240);
+    }
+    if ('details' in result) {
+        return stringifyPreview(result.details, 240);
+    }
+    return '[no tool output]';
+}
+function truncate(value, maxLength) {
+    if (value.length <= maxLength)
+        return value;
+    if (maxLength <= 3)
+        return value.slice(0, maxLength);
+    return `${value.slice(0, maxLength - 3)}...`;
+}
+function condensedArgPreview(_toolName, args) {
+    if (!args || typeof args !== 'object')
+        return stringifyPreview(args, 120);
+    const obj = args;
+    // Show the most meaningful field for common tools
+    if (obj.file_path && typeof obj.file_path === 'string')
+        return obj.file_path;
+    if (obj.command && typeof obj.command === 'string')
+        return truncate(String(obj.command), 120);
+    if (obj.pattern && typeof obj.pattern === 'string')
+        return `pattern: ${obj.pattern}`;
+    if (obj.url && typeof obj.url === 'string')
+        return obj.url;
+    return stringifyPreview(args, 120);
+}

package/dist/agent-events.test.js

@@ -0,0 +1,67 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { handleAgentEvent } from './agent-events.js';
+function createControls(overrides = {}) {
+    return {
+        getAgentName: () => 'Pista',
+        getLiveAssistantText: () => '',
+        appendLog: () => undefined,
+        appendLiveAssistantDelta: () => undefined,
+        clearLiveAssistant: () => undefined,
+        setPendingTools: () => undefined,
+        setRunning: () => undefined,
+        setStatus: () => undefined,
+        ...overrides,
+    };
+}
+test('text deltas are forwarded through the buffered live assistant path', () => {
+    const deltas = [];
+    handleAgentEvent({
+        type: 'message_update',
+        assistantMessageEvent: {
+            type: 'text_delta',
+            delta: 'hello',
+        },
+    }, createControls({
+        appendLiveAssistantDelta: (delta) => {
+            deltas.push(delta);
+        },
+    }));
+    assert.deepEqual(deltas, ['hello']);
+});
+test('assistant message end logs the final text and clears the live buffer', () => {
+    const logs = [];
+    let cleared = 0;
+    handleAgentEvent({
+        type: 'message_end',
+        message: {
+            role: 'assistant',
+            content: [{ type: 'text', text: 'final answer' }],
+        },
+    }, createControls({
+        appendLog: (kind, title, body) => {
+            logs.push({ kind, title, body });
+        },
+        clearLiveAssistant: () => {
+            cleared += 1;
+        },
+    }));
+    assert.deepEqual(logs, [{ kind: 'assistant', title: 'Pista', body: 'final answer' }]);
+    assert.equal(cleared, 1);
+});
+test('assistant message end falls back to buffered live text when needed', () => {
+    const logs = [];
+    handleAgentEvent({
+        type: 'message_end',
+        message: {
+            role: 'assistant',
+            content: [],
+        },
+    }, createControls({
+        getLiveAssistantText: () => 'buffered answer',
+        appendLog: (kind, title, body) => {
+            logs.push({ kind, title, body });
+        },
+    }));
+    assert.deepEqual(logs, [{ kind: 'assistant', title: 'Pista', body: 'buffered answer' }]);
+});