inferoa 0.1.0

package/docs/tui-product-design.md

@@ -0,0 +1,270 @@
+# TUI Product Design
+
+Inferoa should feel like a purpose-built inference-native terminal product,
+not a generic chat prompt.
+
+## Brand Direction
+
+The terminal UI should express:
+
+- vLLM-native inference awareness;
+- fast local/remote endpoint control;
+- long-running coding focus;
+- visible cache/context discipline;
+- precise tool execution.
+
+Visual language:
+
+- dark, high-contrast base;
+- cyan, blue, white, and graphite as the primary palette;
+- sparing amber/red for warnings and destructive states;
+- thin borders, compact panels, and dense but readable information;
+- animated status accents for streaming, endpoint probing, tool execution, and
+  compression;
+- no decorative gradients or unrelated illustrations.
+
+## Default Screen
+
+`inferoa` opens the TUI home/chat surface.
+
+First viewport:
+
+- product wordmark;
+- short workspace path;
+- short session id/title;
+- selected provider and model;
+- compact Omni capability status;
+- git branch and dirty state;
+- context usage and compression status;
+- recent sessions;
+- full-width composer with `/` command discovery and `$` skill
+  discovery.
+
+The default chat banner should not expose base URLs, workspace ids, run ids,
+client ids, cache salts, prompt epoch ids, or other internal routing values.
+Those belong in explicit diagnostic views such as `/endpoints` and
+`/activity`.
+
+The UI should make the product identity obvious without forcing the user through
+a marketing page.
+
+Branding animation:
+
+- the first launch should use a short full-screen intro that establishes the
+  Inferoa mark, then dissolves into the working UI;
+- the animation should use a terminal-native gradient/shine treatment with a
+  fallback for 256-color and narrow terminals;
+- the intro must be skippable with Enter, Space, Escape, or Ctrl-C;
+- the working welcome screen should keep a lighter animated accent, not a
+  constantly distracting full-screen animation.
+
+## Input Model
+
+Supported entrypoints:
+
+- plain text submits a chat turn;
+- `/` opens command palette;
+- `$` opens skill catalog and skill filter;
+- `!` opens shell command helper;
+- file/path mentions trigger local path autocomplete;
+- model/provider selectors are opened from setup or status views;
+- image/video artifacts can be attached or referenced when Omni endpoints are
+  configured.
+
+`inferoa "prompt"` opens the same UI and sends the prompt as the first user
+turn after initialization.
+
+## Setup UX
+
+Setup is scene-based and interactive.
+
+Setup shell:
+
+- full-screen splash;
+- cross-dissolve transition into setup scenes;
+- scene header with Inferoa mark, step count, title, and subtitle;
+- tabbed panels where one setup step contains multiple related choices;
+- modal input for secrets, callback URLs, endpoint probing, and confirmation;
+- footer with keyboard hints;
+- outro transition back to chat.
+
+Provider setup flow:
+
+1. Choose direct vLLM, auto Semantic Router, or external provider.
+2. Enter endpoint URL.
+3. Enter API key in a masked field; setup stores it in the local vault and
+   writes only `api_key_ref`.
+4. Probe `/v1/models`.
+5. Select a model from a TUI list.
+6. Run a minimal capability probe.
+7. Review and save config.
+
+Omni setup flow:
+
+1. Add capability endpoint cards for vision, image generation, video
+   understanding, video generation, audio understanding, and audio generation.
+2. Probe each enabled endpoint independently.
+3. Select model per capability.
+4. Show unavailable capabilities as disabled, not failed.
+
+## Chat Transcript
+
+The transcript should render structured cards:
+
+- user turns;
+- assistant streaming output;
+- tool call pending/running/complete/failed states;
+- file diff preview;
+- shell process output;
+- git summary;
+- todo/activity updates;
+- code-intelligence references;
+- context compression summaries;
+- endpoint evidence;
+- image/video artifacts.
+
+Cards should be compact by default and expandable for large output or managed
+resources.
+
+Tool cards:
+
+- pending/running cards use animated borders or spinner accents with bounded
+  frame rates;
+- completed cards switch to success/error styling without leaving active
+  timers;
+- arguments render inline when collapsed and as a JSON tree when expanded;
+- results use tool-specific renderers instead of generic JSON whenever
+  possible;
+- image results render inline when the terminal supports images and fall back
+  to dimensions/type markers when it does not.
+
+File diff cards:
+
+- show a streaming preview before the edit is applied;
+- avoid jitter from partial streamed JSON by trimming trailing unbalanced
+  removal/hunk lines until the matching additions arrive;
+- show line numbers in a stable gutter;
+- color removed and added lines distinctly;
+- highlight changed tokens inside replaced lines;
+- visualize leading tabs/spaces subtly so indentation edits are visible;
+- syntax-highlight unchanged context lines when a language can be inferred.
+
+## Session UX
+
+`/sessions` is a chat-local overlay, not a separate command screen. It should
+support:
+
+- Resume: attach to an existing non-archived session;
+- New session: create a fresh session in the current workspace;
+- Rename: update the human-readable session title;
+- Archive: hide a completed or stale session from the default list;
+- Show all: include archived sessions and lock state.
+
+Session rows show short session id, title, status, updated time, and a lock
+summary such as `unlocked` or `locked daemon 2m`. They must not show
+`workspace_id`, `run_id`, `client_id`, prompt epoch ids, or cache salts.
+
+Shell/process cards:
+
+- show command header, live output, and cancel hint;
+- throttle high-throughput output updates so rendering cannot starve the event
+  loop;
+- keep full output in resources while the visible panel shows a bounded live
+  preview;
+- support expand/collapse after completion;
+- show exit code, cancellation, hidden-line count, and truncation notices.
+
+Turn footer:
+
+- every assistant turn ends with a compact usage/cache footer;
+- direct vLLM footer fields: prompt tokens, cached prompt tokens, cache hit
+  rate, output tokens, request id, model, endpoint mode, and latency;
+- external provider footer fields: prompt/output tokens and provider usage
+  metadata when available;
+- unsupported cache evidence is displayed as unavailable, not as zero.
+
+## Animation Rules
+
+Animations should communicate state, not decorate.
+
+- streaming assistant text uses a subtle cursor or shimmer;
+- endpoint probing shows a short pulse/spinner and resolves to success,
+  warning, or error;
+- tool execution shows elapsed time and changing status;
+- shell/process output scrolls in a bounded panel;
+- context compression shows a short transition from "archiving" to
+  "summarized";
+- image/video generation shows queued, generating, storing, and ready states.
+
+Animations must stop when the underlying operation stops and must not flood the
+event loop or corrupt terminal resize behavior.
+
+Animation timing:
+
+- setup splash can update around 30 FPS;
+- pending tool borders can redraw up to the renderer's normal frame cadence
+  while advancing spinner glyphs more slowly;
+- high-throughput process output should be throttled and coalesced;
+- todo/activity completion can use a short reveal animation, then settle.
+
+## Status Line
+
+The status line should prioritize:
+
+- provider/model;
+- endpoint mode: direct, auto, external;
+- Omni capability status;
+- workspace short path;
+- session short id/title;
+- git branch;
+- context usage;
+- daemon/job state;
+- permission mode.
+
+Internal ids such as workspace id, run id, client id, prompt epoch id, and cache
+salt do not appear in normal UI.
+
+The status line is not the only evidence surface. Per-turn cache hit rate must
+be visible in the transcript footer so users can see whether a specific request
+hit the vLLM prefix cache.
+
+## Slash Commands
+
+Slash commands are TUI-native commands, not legacy CLI aliases.
+
+Initial command set:
+
+- `/setup`: open setup wizard;
+- `/model`: open model/provider selector;
+- `/endpoints`: open endpoint capability and signal view;
+- `/skills`: open discovered skill picker and enable/disable skills;
+- `/cache`: show per-turn and aggregate cache evidence;
+- `/context`: show context and compression breakdown;
+- `/tools`: show active fixed tool schemas and tool renderer status;
+- `/sessions`: open session picker;
+- `/jobs`: open daemon/supervisor jobs;
+- `/todo`: open task ledger;
+- `/activity`: open the activity ledger and final report resources;
+- `/acceptance`: open final acceptance workflow;
+- `/help`: show keyboard shortcuts and command list;
+- `/exit`: exit the TUI.
+
+Commands that do not map to Inferoa product surfaces should be deleted from
+the active registry rather than retained for compatibility.
+
+## Acceptance UX
+
+Final acceptance should be visible as a TUI workflow:
+
+- preflight endpoint checklist;
+- AMD deployment checklist;
+- external provider checklist;
+- coding task progress;
+- tool coverage checklist;
+- compression evidence;
+- Omni artifact checklist;
+- daemon attach/detach/status/cancel checklist;
+- final evidence report.
+
+The TUI may call automation underneath, but the user should be able to watch
+and inspect the acceptance run from the terminal app.

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "inferoa",
+  "version": "0.1.0",
+  "description": "Inference-optimized agent for long-horizon tasks in the vLLM ecosystem.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "inferoa": "./dist/src/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentic-in/inferoa.git"
+  },
+  "homepage": "https://inferoa.agentic-in.ai/",
+  "bugs": {
+    "url": "https://github.com/agentic-in/inferoa/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agent",
+    "vllm",
+    "inference",
+    "coding-agent",
+    "prefix-cache"
+  ],
+  "files": [
+    "dist/src",
+    "skills",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/*.test.js",
+    "prepack": "npm run build",
+    "site:start": "npm --prefix website run start",
+    "site:build": "npm --prefix website run build",
+    "site:serve": "npm --prefix website run serve",
+    "validate:t0": "npm run build && node dist/src/validation/milestone.js T0",
+    "validate:t1": "npm run build && node dist/src/validation/milestone.js T1",
+    "validate:t2": "npm run build && node dist/src/validation/milestone.js T2",
+    "validate:t3": "npm run build && node dist/src/validation/milestone.js T3",
+    "validate:t4": "npm run build && node dist/src/validation/milestone.js T4",
+    "validate:t5": "npm run build && node dist/src/validation/milestone.js T5",
+    "validate:t6": "npm run build && node dist/src/validation/milestone.js T6",
+    "validate:t7": "npm run build && node dist/src/validation/milestone.js T7",
+    "validate:t8": "npm run build && node dist/src/validation/milestone.js T8",
+    "validate:t9": "npm run build && node dist/src/validation/milestone.js T9",
+    "validate:t10": "npm run build && node dist/src/validation/milestone.js T10",
+    "validate:all": "npm run build && for milestone in T0 T1 T2 T3 T4 T5 T6 T7 T8 T9 T10; do node dist/src/validation/milestone.js $milestone || exit 1; done"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@colbymchenry/codegraph": "0.9.9",
+    "commander": "^14.0.2",
+    "typescript": "^5.9.3",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1"
+  }
+}

package/skills/coding-workflow/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: "coding-workflow"
+description: "Default Inferoa coding workflow: inspect, plan, edit, test, record evidence, and preserve context."
+---
+
+# Coding Workflow
+
+Use repository files and docs as the source of truth. For non-trivial work:
+
+1. Inspect the relevant files before editing.
+2. Use `file_search`, `read_file`, and code-intelligence tools where supported.
+3. Keep a task ledger with `todo_write` and evidence with `complete_step`.
+4. Prefer `apply_patch` or structured edits for source changes.
+5. Run targeted validation through `run_command`.
+6. Store bulky outputs as resources and read only bounded pages.
+7. Continue after context compression using the summary plus recent tail.