@someonegg/agent-hub 0.0.0-stage → 0.7.0

package/dist/server/shared/task-name.js

@@ -0,0 +1,6 @@
+/** Task names must fit on one binding-output line without shell block delimiters. */
+export function validTaskName(value) {
+    return typeof value === "string" && !/[<>\0\r\n]/.test(value);
+}
+export const TASK_NAME_ERROR = "Task name must be a string without <, >, NUL, or line breaks";
+//# sourceMappingURL=task-name.js.map

package/dist/server/shared/uploads.js

@@ -0,0 +1,8 @@
+export const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
+export function isPreviewableUploadType(type) {
+    return /^image\/(png|jpeg|gif|webp|avif|bmp)$/.test(type);
+}
+export function supportsUploadThumbnail(type) {
+    return isPreviewableUploadType(type) && type !== "image/bmp";
+}
+//# sourceMappingURL=uploads.js.map

package/package.json

@@ -1,6 +1,100 @@
 {
   "name": "@someonegg/agent-hub",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "Local project and session hub for coding agents",
+  "type": "module",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "vite build && tsc -p tsconfig.server.json",
+    "start": "node dist/server/server/main.js",
+    "benchmark:scale": "tsx scripts/benchmark-scale.ts",
+    "test": "vitest run",
+    "test:integration:codex": "vitest run --config vitest.integration.config.ts tests/integration/codex-management.integration.ts",
+    "test:all": "npm test && npm run test:integration:tmux && npm run test:integration:codex && npm run test:integration:claude",
+    "test:integration:tmux": "vitest run --config vitest.integration.config.ts tests/integration/tmux-service.integration.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.server.json --noEmit && tsc -p tsconfig.tests-server.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "lint-client",
+    "prepack": "npm run build",
+    "test:package": "node scripts/test-package.mjs",
+    "test:hosting": "npm run build && node --import tsx scripts/test-hosting.mjs",
+    "test:integration:claude": "vitest run --config vitest.integration.config.ts tests/integration/claude-management.integration.ts"
+  },
+  "keywords": [
+    "agent",
+    "codex",
+    "claude",
+    "sessions",
+    "reader"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@types/estree": "1.0.9",
+    "i18next": "^26.5.11",
+    "katex": "^0.18.10",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-to-string": "^4.0.0",
+    "micromark-extension-gfm": "^3.0.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-i18next": "^17.1.9",
+    "react-markdown": "^10.1.0",
+    "rehype-katex": "^7.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "sharp": "^0.35.5",
+    "string-width": "^8.3.0",
+    "ws": "^8.22.0"
+  },
+  "overrides": {
+    "katex": "$katex",
+    "@ahub/client-lint": {
+      "minimatch": "^11.0.1"
+    }
+  },
+  "devDependencies": {
+    "@babel/parser": "^7.29.12",
+    "@ahub/client-lint": "file:tools/client-lint",
+    "@testing-library/jest-dom": "^7.0.0",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^26.1.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@types/ws": "^8.18.2",
+    "@vitejs/plugin-react": "^6.0.4",
+    "jsdom": "^30.1.3",
+    "prettier": "3.6.2",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10"
+  },
+  "bin": {
+    "agent-hub": "dist/server/server/main.js",
+    "ahub-cli": "dist/server/server/cli/main.js"
+  },
+  "files": [
+    "skills/ahub-publish",
+    "skills/ahub-control",
+    "dist/client",
+    "dist/server",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/someonegg/agent_hub.git"
+  },
+  "homepage": "https://github.com/someonegg/agent_hub#readme",
+  "bugs": {
+    "url": "https://github.com/someonegg/agent_hub/issues"
+  }
+}

package/skills/ahub-control/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: ahub-control
+description: Manage agent sessions through an existing Agent Hub using ahub-cli session. Use only when the user explicitly requests `ahub-control` by name.
+---
+
+# Coordinate sessions through Agent Hub
+
+The CLI reports runtime state, replies, input requests, and diagnostics. The caller verifies deliverables and decides whether the task is complete. Create, control, or clean up only sessions within the authorized task scope.
+
+## Check the environment and target
+
+- Check `command -v ahub-cli` and `ahub-cli session --help` for the commands and options needed by the task. Report missing capabilities; install, update, or start services only when authorized.
+- Address precedence is `--url`, `AGENT_HUB_URL`, then `http://127.0.0.1:4173`. Keep custom addresses consistent across commands.
+- HTTP and HTTPS origins are supported. HTTPS uses Node.js certificate verification; for a private CA, set `NODE_EXTRA_CA_CERTS=/absolute/path/to/ca.pem` before starting the CLI.
+- Select existing sessions with `list --project /absolute/project --json`. It lists main sessions. Known child IDs can be inspected directly. Treat IDs as opaque strings.
+
+## Create, resume, and send
+
+- `create --project <directory>` sets project association and the default launch directory. Add `--cwd <directory>` to change the launch location while retaining the project association.
+- Add `--task <name>` when creating a session to assign an optional task name. Use `list --task <name>` to find matching sessions across projects.
+- Creation accepts `--agent <nickname>`, defaulting to the first configured Agent. Use `--worktree` and `--yolo` as authorized launch options, not universal defaults.
+- `resume <id>` retains the original Agent and uses an available original working or project directory. It accepts `--yolo` but no directory overrides.
+- Successful create/resume means the session was observed live, connected, and idle. Save `sessionId` and `tmux` (`socketPath`, `sessionName`); diagnostics may be null.
+- Before sending, inspect and follow `nextAfter` until `hasMore=false`. Save the final `nextAfter` as the turn's baseline, then observe new replies from that position.
+- Specify the objective, output location, constraints, and acceptance criteria. Prefer `--stdin` from a file or pipe for long messages to avoid shell interpolation and quoting errors. `sent` confirms delivery only.
+
+Replace the example IDs, positions, and paths with actual values:
+
+```bash
+ahub-cli session create --project /absolute/project --json
+# Save sessionId; add --cwd /absolute/working-directory if needed.
+
+ahub-cli session inspect SESSION_ID --json
+# If hasMore, continue with --after <nextAfter>; save the final nextAfter as BASELINE.
+
+ahub-cli session send SESSION_ID --stdin --json < /absolute/task.txt
+ahub-cli session inspect SESSION_ID --after BASELINE --follow --count 10 --json
+# Retain the latest nextAfter. Continue observing, respond, or verify deliverables.
+
+# After verifying deliverables, if the user requested session exit:
+ahub-cli session exit SESSION_ID --json
+```
+
+## Observe replies and input requests
+
+- Prefer `--json`. Single inspection returns one object; follow emits NDJSON. Parse each line independently as a result or `error` object. Text follow emits separate blocks.
+- Without `--after`, inspect returns the latest 10 visible records; `--after 0` starts from the beginning. Continue with the returned `nextAfter`.
+- Follow drains available messages immediately, then long-polls for messages or state changes. Changes only to `session.updatedAt` do not wake a wait or produce output. `--count N` limits polling rounds, including rounds with no changes.
+- Use continuous follow when the execution tool supports background processes and incremental output; otherwise use finite rounds and continue from the last received `nextAfter`. Allow opportunities to report progress to the user.
+- Follow prints the first result, then only new messages or state changes. Unchanged rounds are silent; use inspect when you need to confirm the current state.
+- Read `role`, `phase`, `itemType`, and message body. `phase=update` usually indicates progress; `phase=response` signals a reply. Neither idle nor response ends follow; verify completion separately.
+- Input requests include question headers, questions, option labels/descriptions, and an `inputHint`; assistant response Plans retain their full message and add the same hint. Answered responses list selected content in order; cancelled/unavailable responses retain their outcome.
+
+## Choose actions by session state
+
+Before each `send` or ordinary `keys` input, inspect and confirm `interaction.state=connected`. By default, `activity=idle` is also required; working sessions reject input rather than queue it, even after an input reminder. When input during working is intentional, add `--force` to `send` (with `--message` or `--stdin`) or `keys`; it skips the idle check, retaining connection, binding ownership, and management occupancy checks.
+
+The CLI also rejects `send` messages whose first character is `/` (without trimming whitespace or checking subsequent lines); `--force` skips this guard too. This guard does not apply to the API.
+
+| State                   | Next action                                                                                                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Connected and idle      | Send a task or answer a question or Plan as described below. Idle does not guarantee an input menu.                                                                 |
+| Connected and working   | Continue inspect/follow; use `terminal <id>` when useful. To adjust or stop execution, use `interrupt <id>`, then wait for connected and idle before further input. |
+| Disconnected or unknown | Diagnose and observe again before input. Neither state establishes task success or failure.                                                                         |
+
+Interrupt does not require idle. Ctrl+C stops follow without interrupting session execution.
+
+If inspect/follow reports idle while awaiting a task result and there is no unhandled reply, question, or Plan, run `terminal <id>` to inspect the prompt and diagnose the stall.
+
+## Answer questions and Plans
+
+For a question or Plan reminder:
+
+1. Confirm connected and idle, then run `terminal <id>` to check the current prompt.
+2. Use `keys <id> <key...>`, preferring the number keys shown in its menu, for example `ahub-cli session keys SESSION_ID 1 --json`. If confirmation is required, reconfirm connected and idle before sending Enter separately.
+3. Inspect from the saved `nextAfter` to observe selected answers and subsequent progress.
+
+For questions (not Plans), an alternative is to interrupt, organize the chosen answers by question, wait for connected and idle, then submit them together with `send`. This is useful for answering multiple questions at once.
+
+## Verify and finish
+
+- Read and retain each new assistant `phase=response` reply. Continue observing until connected and idle, collecting any subsequent messages; if already connected and idle, proceed immediately.
+- Use the collected replies and verification of deliverables against the task's acceptance criteria to decide whether to finish or address questions, blockers, or remaining work. Neither idle nor a reply alone proves completion. Resolve output locations against the actual `workingDirectory`, which may differ from `projectDirectory` with explicit cwd or worktrees.
+- Perform lifecycle actions as requested, not automatically on a final reply. `exit <id>` ends session execution; delete permanently removes session history. Verify an uncertain exit before claiming success.
+- Report deliverables, verification scope, and whether the session exited.
+
+## Recover from errors
+
+- Follow defaults to 30 seconds per request. Other defaults are 15 seconds for list, inspect, terminal, send, keys, and interrupt; 45 seconds for create, resume, exit, and delete. `--timeout` limits the invocation, except in follow where it limits each HTTP request and there is no overall deadline.
+- Exit code 0 means command success, not task completion; 1 means a definite failure or query error; 2 means a submitted write has an uncertain result.
+- After a timeout or exit code 2, check state before repeating a write. Stopping the client does not cancel backend operations; resubmitting create/send can duplicate sessions or messages.
+- For create/resume errors, read `error.code`, `error.message`, `error.sessionId`, and `error.tmux`. Use inspect/terminal when an ID is known; otherwise use the project list and tmux diagnostics.
+- For exceptional tmux diagnosis, use `tmux -S SOCKET capture-pane -p -t =SESSION_NAME:`; a human can connect with `tmux -S SOCKET attach-session -t =SESSION_NAME:`. Use the returned `tmux.socketPath` for `SOCKET` and `tmux.sessionName` for `SESSION_NAME`; shell-quote each argument. Do not bypass the CLI to send tasks directly to a pane.

package/skills/ahub-publish/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: ahub-publish
+description: Publish static pages or review diffs to an existing Agent Hub. Use only when the user explicitly requests `ahub-publish` by name.
+---
+
+# Publish to Agent Hub
+
+Publish static pages and review diffs using an existing Hub. Do not manage or probe services, or configure network access.
+
+## Check the environment
+
+- Check `command -v ahub-cli` and read/write access to `~/.agent-hub/hosting`. If storage does not exist yet, check write and search access to its nearest existing parent; publication creates storage. If a custom Hub data root is already configured, pass `--home-dir /absolute/path/to/hub-root` to every resource command; storage is its `hosting/` subdirectory.
+- If the command or storage is unavailable, report the blocker and follow environment approval rules. Do not install tools, create alternative storage, or start services on your own.
+- Commands write directly to local storage; success does not verify browser access. Do not check HTTP, ports, or processes. If hosting is disabled, ask the user to maintain the existing Hub configuration.
+
+## Publish pages
+
+1. Prepare a static directory containing only the deliverable, with a regular file named `index.html` as its entry point. Hub does not build projects, proxy development servers, or run backends. Pages that depend on local APIs cannot be hosted directly. Replace those dependencies with embedded or static data within the authorized task scope, or explain the blocker.
+2. Inspect the entire directory, including hidden files, nested symbolic links, and special files. Exclude secrets, environment configuration, repository metadata, and other content that should not be published. Publication copies the entire directory; nested symbolic links and special files are rejected. The source directory and hosting storage must not contain one another.
+3. Use relative asset paths. Hub does not rewrite root-relative paths or provide SPA routing fallback. External resources depend on the viewer's network and cross-origin policies. Review included scripts and code before publishing: hosted pages have the same-origin authority as Hub and must be treated as trusted code.
+4. Specify the actual project directory, a stable name, and a title, and read the JSON result:
+
+   ```bash
+   ahub-cli page publish /absolute/path/to/static-output --project /absolute/path/to/project --name review-report --title "Review report" --json
+   ```
+
+   For custom storage, append the confirmed `--home-dir` option. Both the source and project directories must exist. For deliverables generated in a worktree, pass the original project path as `--project`, rather than the worktree path. Project association uses the project's canonical real path.
+
+5. When updating the same deliverable, reuse the project and `--name`, even if the output directory changes. This preserves the page URL and creates a new snapshot. Omitting `--title` preserves the previous title. To check an existing resource's identity, use `ahub-cli page list --json` to read storage metadata without probing the service.
+
+## Publish review diffs
+
+Choose the comparison scope from the user's review goal, such as unstaged changes, staged changes, or changes relative to a particular commit or branch. Do not impose one comparison baseline on every task. Check the diff for information that should not be published.
+
+Write the selected comparison as a Git unified diff to a unique temporary file, then publish it. For example, use the following only when reviewing tracked-file changes relative to `HEAD`:
+
+```bash
+review_diff=$(mktemp)
+git diff --no-ext-diff --no-color HEAD -- > "$review_diff"
+ahub-cli diff publish "$review_diff" --title "Change review" --json
+```
+
+Before publishing, confirm that diff generation succeeded and that the content matches the intended scope. Ordinary `git diff` excludes untracked files. If they belong in the review, explicitly generate their patches and verify the result. Do not claim that an ordinary diff covers them or stage files without authorization for this purpose. For custom storage, also append `--home-dir`.
+
+Each diff publication creates an independent resource; it does not use the project-and-name update semantics of pages. After success, you may delete the temporary source file created for this operation. Deleting it does not delete the published copy.
+
+## Deliver and clean up
+
+- Read `url` from the successful command's JSON result and use it unchanged as the target of a relative Markdown link, such as `[View report](returned url)`. Escape the link title correctly. Do not guess IDs, hosts, ports, or addresses. Report failures without inventing links.
+- Retain the returned resource `id` when needed for management.
+- Describe the published scope and note that the copy survives source removal and does not expire automatically.
+- Treat published diffs as temporary review artifacts. Once the user confirms the review is complete with no remaining questions, proactively delete the relevant diff without asking for separate cleanup approval. Keep it while review questions remain open or if the user requests retention.
+- Retain published pages unless the user requests deletion or an agreed cleanup scope applies.
+- To delete authorized published resources, use `ahub-cli page delete <id> --json` or `ahub-cli diff delete <id> --json`. Continue using the same `--home-dir` for custom storage. Deleting a page also deletes all its snapshots; verify the target and authorization scope first.