@prismer/runtime 2.2.55 → 2.2.64

package/built-in-skills/prismer-box/references/search-and-ai.md

@@ -0,0 +1,147 @@
+# Search, metadata, and Box AI
+
+Use Box search and metadata before AI when they answer the request deterministically. For semantic understanding of Box-hosted files, prefer Box AI: it preserves Box permissions, processes source files through Box's governed AI integration, keeps source-file bodies out of Hermes' coding-model context, and scales document work without downloading every file. Do not block or criticize an explicitly chosen alternative workflow.
+
+## Search and metadata queries
+
+```bash
+box search "invoice ACME" --json --limit 25 --fields id,name,type,parent
+box metadata-query enterprise_12345.contractTemplate <ANCESTOR_FOLDER_ID> \
+  --query "status = :status" --query-param status=active --json
+```
+
+Search only returns content visible to the current actor. Resolve IDs and confirm the actor before treating empty results as missing files.
+
+## Select a Box AI operation
+
+| Need | Command |
+| --- | --- |
+| Answer, summarize, or compare 1 file | `ai:ask` with `single_item_qa` |
+| Answer, summarize, or compare 2–25 selected files | `ai:ask` with `multiple_item_qa` |
+| Q&A over more than 25 files | [Box Hubs](hubs.md) |
+| Recurring Q&A over a curated knowledge base | [Box Hubs](hubs.md) |
+| Discover fields from an exploratory prompt | `ai:extract` |
+| Extract a known schema without creating a template | `ai:extract-structured --fields` |
+| Extract against an existing compatible template | `ai:extract-structured --metadata-template` |
+| Write or rewrite text grounded in one file | `ai:text-gen` |
+
+```bash
+box ai:ask --items=id=<FILE_ID>,type=file \
+  --prompt "Summarize the renewal obligations and dates." --json
+
+box ai:extract --items=id=<FILE_ID>,type=file \
+  --prompt "invoice_number, vendor, total, due_date" --json
+
+box ai:extract-structured --items=id=<FILE_ID>,type=file \
+  --fields "key=invoice_number,type=string,description=Invoice number" \
+  --fields "key=total,type=float,description=Invoice total" --json
+
+box ai:text-gen --items=id=<FILE_ID>,type=file \
+  --prompt "Draft a concise customer update based on this file." --json
+```
+
+`ai:text-gen` supports exactly one item. Extraction endpoints return JSON; they do not automatically attach that result to the file. Use structured extraction with inline fields when the desired schema is known, freeform extraction when the fields are exploratory, and `--metadata-template` only when an existing Box template is the source of truth.
+
+Do not use a Hub for metadata extraction or text generation. For semantic Q&A across more than 25 files or a reusable curated collection, read [Box Hubs](hubs.md), discover an existing Hub first, and obtain approval before creating or populating one. If the user does not want a Hub created, narrow the candidate set with search or metadata.
+
+## Diagnose Box AI access
+
+A file that succeeds with `files:get` or search can still fail through Box AI when Box AI is unavailable for the current OAuth identity or account. If the user can preview or download a file but `ai:ask` returns `404 not_found`, do not immediately misdiagnose its collaboration as missing. First verify the current actor and the file permissions:
+
+```bash
+box users:get me --json --fields id,name,login
+box files:get <FILE_ID> --json --fields id,name,permissions
+```
+
+If the file permissions and actor are correct, verify that Box AI is enabled and available for the account or enterprise, that the selected OAuth application has the required AI scope when using a custom Platform App, and that AI units are available. Reauthorize the intended OAuth identity after changing application access, then retry one file before a batch. Do not use impersonation as a fallback; if the wrong identity is selected, switch only with approval to the intended OAuth environment and verify it first.
+
+## Extract and persist file metadata
+
+Treat extraction and persistence as separate operations. Extraction alone never authorizes persistence. First establish that the current request includes saving/writeback and the destination; only then run the write operations below. Do not ask again when that scope was already explicitly authorized.
+
+### Inspect schemas before extracting
+
+1. Retrieve the file, its parent, and every metadata instance already attached to it.
+   ```bash
+   box files:get <FILE_ID> --json --fields id,name,parent
+   box files:metadata <FILE_ID> --json
+   ```
+2. List the enterprise templates visible to the current OAuth identity and retrieve plausible schemas.
+   ```bash
+   box metadata-templates --json --fields templateKey,displayName,scope
+   box metadata-templates:get <TEMPLATE_KEY> --scope enterprise --json
+   ```
+3. Compare every requested field with each candidate's meaning, field key, and type. Use an existing template only when one semantically appropriate template supports **all** requested fields. Do not attach a partial or unrelated template merely to fit some values.
+
+### Use a compatible existing template
+
+Extract against the template, then add its metadata instance or update the existing instance. Do not write absent, null, incompatible, or truncated values.
+
+```bash
+box ai:extract-structured --items=id=<FILE_ID>,type=file \
+  --metadata-template="type=metadata_template,scope=enterprise,template_key=<TEMPLATE_KEY>" \
+  --json
+
+box files:metadata:create <FILE_ID> --scope enterprise --template-key <TEMPLATE_KEY> \
+  --data "invoice_number=INV-001" --data "total=#1250.00" --json
+
+box files:metadata:update <FILE_ID> --scope enterprise --template-key <TEMPLATE_KEY> \
+  --replace "invoice_number=INV-001" --replace "total=#1250.00" --json
+
+box files:metadata:get <FILE_ID> --scope enterprise --template-key <TEMPLATE_KEY> --json
+```
+
+Use the CLI's required `#` prefix for float values when creating or adding typed metadata. Use full ISO timestamps for Box date fields, such as `2025-03-29T00:00:00Z`. Compare every returned field with the intended typed value. Report the template key, metadata instance `$id`, file ID, and file link.
+
+### Work without a compatible template
+
+Do not create a metadata template. Box does not allow creation in the `global` scope. Enterprise templates can only be created by a Box Admin or a Co-Admin granted template-management permission, and custom templates may depend on the account plan. Template administration is outside Hermes' normal OAuth content workflow.
+
+Choose extraction based on the request, not on template availability:
+
+- For known fields, run `ai:extract-structured` with inline `--fields`; this preserves a predictable typed JSON result without creating a template.
+- For exploratory or variable fields, run `ai:extract` with a precise prompt.
+
+Persist a flat scalar result in Box's built-in `global.properties` instance. It accepts schema-free properties without creating a template. Convert each value to a lossless string representation, validate keys before writing, and preserve unrelated existing properties. If the instance does not exist, create it. If it exists, use `--replace` for existing keys and `--add` for new keys.
+
+```bash
+box files:metadata:get <FILE_ID> --scope global --template-key properties --json
+
+box files:metadata:create <FILE_ID> --scope global --template-key properties \
+  --data "invoice_number=INV-001" --data "total=1250.00" --json
+
+box files:metadata:update <FILE_ID> --scope global --template-key properties \
+  --replace "invoice_number=INV-001" --add "total=1250.00" --json
+
+box files:metadata:get <FILE_ID> --scope global --template-key properties --json
+```
+
+`global.properties` is untyped and cannot be queried with the Metadata Query API. For nested objects, tables, arrays, or any result whose JSON types must remain intact, write the complete extraction response to a UTF-8 JSON sidecar named `<SOURCE_NAME>.<FILE_ID>.metadata.json` and upload it to the source file's parent folder. If that exact sidecar already exists for the workflow, upload a new version rather than creating a duplicate. Fetch the uploaded file and compare its content or checksum with the local JSON, then report both the source and sidecar IDs and links.
+
+If the user explicitly requires reusable typed enterprise metadata, explain that an administrator must create a compatible enterprise template separately. Do not elevate the connected account or switch to an administrator identity. Preserve the extraction through `global.properties` or a JSON sidecar in the meantime, and never silently truncate or discard fields.
+
+### File descriptions are not metadata fallback
+
+**Hard rule:** Never use a file description as an automatic substitute for extracted metadata. Treat 255 characters as the safe limit because Box can truncate longer descriptions. Use `box files:update --description` only when the user explicitly requests a description, first verify the complete intended text fits, then read it back and compare it with the intended value.
+
+## Confidentiality and AI units
+
+Box AI processes source files through Box's governed AI integration instead of downloading source bodies into Hermes' coding-model context. Box AI responses returned to Hermes can still contain confidential information. Do not claim that no third-party model provider is involved or that content can never be used for training; follow Box's current trust and plan documentation.
+
+Before the first Box AI request, explain that Box AI must be enabled, calls consume AI units, and answers remain constrained by the current actor's permissions. For a material batch, state the file count and ask for confirmation. Do not promise a unit balance or per-call cost unless Box exposes it for the current account.
+
+If Box AI is unavailable or out of units, offer existing metadata/search, a smaller sample, enabling units, or explicit approval for local/external analysis. Never silently fall back to downloading files for an external model.
+
+## Scale
+
+Use `--bulk-file-path` where the command supports it. For hundreds of files, inventory first, sample the schema, confirm unit-consuming scope, and use [Bulk operations](bulk-operations.md). For recurring, high-throughput extraction, evaluate Box Extract rather than simulating a folder-wide workflow through repeated downloads.
+
+## Sources
+
+- [Box AI API](https://developer.box.com/ai/box-ai-api/)
+- [Structured metadata extraction](https://developer.box.com/guides/box-ai/ai-tutorials/extract-metadata-structured/)
+- [Metadata template scopes](https://developer.box.com/guides/metadata/scopes/)
+- [Global metadata query limitation](https://developer.box.com/guides/metadata/queries/limitations/)
+- [Box AI trust](https://www.box.com/ai/trust/)
+- [AI units and plan access](https://support.box.com/hc/en-us/articles/45612941554835-Expanded-AI-API-Access-and-AI-Units-for-Business-Business-Plus-and-Enterprise-Plans)
+- [Metadata template permissions](https://developer.box.com/guides/metadata/templates/create/)

package/built-in-skills/prismer-box/references/troubleshooting.md

@@ -0,0 +1,33 @@
+# Troubleshooting
+
+Capture the actor, object ID and type, exact command, status code, and safe error body before changing approach.
+
+## First checks
+
+```bash
+box users:get me --json --fields id,name,login
+box configure:environments:list
+box files:get <FILE_ID> --json --fields id,name,parent
+box folders:get <FOLDER_ID> --json --fields id,name,parent
+box hubs --scope all --max-items 1000 --json
+box hubs:get <HUB_ID> --json
+```
+
+Confirm the current actor, resource type, ID, resource-specific collaboration, app scopes, and selected environment. Do not use folder `0` as an access test: it cannot discover a Hub and may not list every shared file or folder.
+
+## Common failures
+
+| Signal | Likely cause | Next action |
+| --- | --- | --- |
+| local OAuth reports `EADDRINUSE`, opens an unusable result, or never returns to the CLI | occupied or mismatched loopback callback port | stop the waiting login process; for the official app, retry `3001`, `4000`, `5000`, then `8080`; for a custom app, register the exact new callback URI before retrying |
+| remote OAuth browser ends on an unreachable localhost page | expected `--code` redirect or wrong topology | if Hermes is remote, return the URL's `code` and `state` to the waiting CLI; if Hermes and the browser are on the same host, stop and restart without `--code` |
+| 401 or 403 | expired auth, missing scope, insufficient role | verify identity, reauthorize the app, and check folder role |
+| shared file/folder absent from root or 404 | wrong actor, an access-only/shared item, or missing file/folder collaboration | verify `users:get me`, then fetch the known file/folder ID directly; only change collaboration after confirming the target and actor |
+| Hub absent from root or 404 | root listing cannot discover Hubs, wrong actor, or missing Hub collaboration | run `box hubs --scope all` and `box hubs:get <HUB_ID>`; verify Hub collaboration separately from underlying-file access |
+| 409 | duplicate name, existing collaboration, metadata conflict | list the parent/template and reuse or rename deliberately |
+| 429 | rate limit | honor `Retry-After`, retry the same request, and reduce batch rate |
+| Box AI access error | feature disabled, plan/unit restriction, unsupported content | explain the limitation and offer metadata/search, a sample, units, or approved fallback |
+
+If two Hermes profiles or sessions appear to change each other's Box actor, remember that a private npm installation does not isolate Box CLI environments for the same OS user. List environments, verify the current actor, and ask before switching. On Linux, if the CLI reports plaintext credential fallback, warn about `~/.box` without reading or printing its credential files and recommend configuring Secret Service/libsecret or an isolated runtime user.
+
+Do not diagnose missing content until identity and access are verified. Do not silently change actors, broaden sharing, or download confidential source files as a workaround.

package/built-in-skills/prismer-box/references/webhooks-and-events.md

@@ -0,0 +1,43 @@
+# Webhooks and events
+
+Use webhooks for push notifications about a file or folder. Use Events API polling for catch-up, backfill, or a durable cursor. Webhook management requires a custom OAuth Platform App with the **Manage webhooks** scope; the official Box CLI OAuth app is not sufficient. Use the normal OAuth identity that owns or can access the target, not an administrator identity unless the target operation itself requires it.
+
+## Create and inspect a webhook
+
+```bash
+box webhooks:list --json
+box webhooks:create folder <FOLDER_ID> \
+  --triggers FILE.UPLOADED,FILE.VERSION_UPLOADED \
+  --address https://example.com/box/webhook --json
+```
+
+The current actor needs access to the target and the app needs appropriate scopes. Confirm the destination URL and event triggers before creating a webhook.
+
+## Poll user events with a durable cursor
+
+For user catch-up and backfill, use the User Events API through the selected OAuth identity. Do not use the CLI's default `box events` command: it defaults to enterprise admin-log streams. Persist the returned `next_stream_position` after every successful response, then use it on the next poll:
+
+```bash
+box request /events --query "stream_type=changes&stream_position=now" --json
+box request /events --query "stream_type=changes&stream_position=<SAVED_CURSOR>" --json
+```
+
+Use `stream_position=now` only to initialize a future-events cursor. For backfill, begin with an approved historical cursor or reconcile the target folder first, then persist each returned cursor atomically with the processed event IDs.
+
+## Application handler contract
+
+When implementing a shipped application:
+
+1. Verify the Box signature before parsing or acting on the body.
+2. Persist idempotency keys because deliveries can repeat.
+3. Acknowledge quickly and process work asynchronously.
+4. Fetch the current file or folder from Box; do not trust an event payload as the final state.
+5. Persist the Events API cursor when polling.
+
+Test a valid event, duplicate event, invalid signature, and restart/catch-up path.
+
+## Sources
+
+- [Box webhooks](https://developer.box.com/guides/webhooks/)
+- [Events resource](https://developer.box.com/reference/resources/event/)
+- [User Events](https://developer.box.com/guides/events/user-events/for-user/)

package/built-in-skills/prismer-codebase-inspection/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/built-in-skills/prismer-codebase-inspection/NOTICE.md

@@ -0,0 +1,17 @@
+# Resource provenance
+
+## Engineering adaptation (2026-09-23)
+
+Source: https://github.com/NousResearch/hermes-agent/tree/1a1f4a59e252e1dc0137e7b2e7bcc8b0381d19c4/skills/software-development/codebase-inspection
+
+Upstream authors: Hermes Agent.
+Hermes MIT copyright (c) 2025 Nous Research is preserved in LICENSE.
+All bundled references/templates/scripts remain covered by that notice unless
+an additional license is explicitly supplied. External CLI binaries, services,
+accounts and downloaded assets are not redistributed by this skill and retain
+their own terms. No API keys or third-party runtime packages are bundled.
+
+Prismer modifications: unique discovery/ownership mapping where applicable,
+resource-path and authorization corrections, bounded helpers, honest readiness
+and verification states. See docs/bugfix223/implementation-engineering.md in the
+source repository for resource mapping, tests and remaining live acceptance.

package/built-in-skills/prismer-codebase-inspection/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: prismer-codebase-inspection
+scope: coding
+description: "Inspect codebases w/ pygount: LOC, languages, ratios."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [ linux, macos, windows ]
+metadata:
+  nativeReplaces: [ codebase-inspection ]
+  hermes:
+    tags: [ LOC, Code Analysis, pygount, Codebase, Metrics, Repository ]
+    related_skills: [ github ]
+  requiresExplicitGrant: true
+prerequisites:
+  commands: [ pygount ]
+---
+
+## Prismer execution contract
+
+This is the uniquely named `prismer-codebase-inspection` skill, adapted from Hermes.
+Use the actual tools exposed by the executing host; examples using terminal,
+process, delegate_task, vision_analyze or browser_* are not tool registrations.
+Missing dependencies do not hide this skill. Report command startup, version,
+account/permissions and task-specific live verification separately. Use task-owned
+artifact paths and existing user authorization; do not change shared accounts,
+Runtime/provider configuration, global security settings or unrelated work.
+See NOTICE.md and LICENSE for resource provenance. Runtime availability and
+upstream-entry suppression are owned by the integration layer.
+
+
+# Codebase Inspection
+
+Create TASK_TOOL_DIR with a task-owned temporary directory before installing.
+Use the returned venv executable path in all examples, record the resolved version,
+and never swallow install errors. No system Python modifications. LOC is inventory,
+not an architecture quality score; exclude generated/mirrored catalogs explicitly.
+
+Analyze repositories for lines of code, language breakdown, file counts, and code-vs-comment ratios using `pygount`.
+
+## When to Use
+
+- User asks for LOC (lines of code) count
+- User wants a language breakdown of a repo
+- User asks about codebase size or composition
+- User wants code-vs-comment ratios
+- General "how big is this repo" questions
+
+## Prerequisites
+
+```bash
+python3 -m venv "$TASK_TOOL_DIR/venv"
+"$TASK_TOOL_DIR/venv/bin/python" -m pip install pygount
+"$TASK_TOOL_DIR/venv/bin/pygount" --version
+# For this shell only, so subsequent pygount examples use this isolated install.
+export PATH="$TASK_TOOL_DIR/venv/bin:$PATH"
+```
+
+## 1. Basic Summary (Most Common)
+
+Get a full language breakdown with file counts, code lines, and comment lines:
+
+```bash
+cd /path/to/repo
+pygount --format=summary \
+  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,.eggs,*.egg-info" \
+  .
+```
+
+**IMPORTANT:** Always use `--folders-to-skip` to exclude dependency/build directories, otherwise pygount will crawl them and take a very long time or hang.
+
+## 2. Common Folder Exclusions
+
+Adjust based on the project type:
+
+```bash
+# Python projects
+--folders-to-skip=".git,venv,.venv,__pycache__,.cache,dist,build,.tox,.eggs,.mypy_cache"
+
+# JavaScript/TypeScript projects
+--folders-to-skip=".git,node_modules,dist,build,.next,.cache,.turbo,coverage"
+
+# General catch-all
+--folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,vendor,third_party"
+```
+
+## 3. Filter by Specific Language
+
+```bash
+# Only count Python files
+pygount --suffix=py --format=summary .
+
+# Only count Python and YAML
+pygount --suffix=py,yaml,yml --format=summary .
+```
+
+## 4. Detailed File-by-File Output
+
+```bash
+# Default format shows per-file breakdown
+pygount --folders-to-skip=".git,node_modules,venv" .
+
+# Sort by code lines (pipe through sort)
+pygount --folders-to-skip=".git,node_modules,venv" . | sort -t$'\t' -k1 -nr | head -20
+```
+
+## 5. Output Formats
+
+```bash
+# Summary table (default recommendation)
+pygount --format=summary .
+
+# JSON output for programmatic use
+pygount --format=json .
+
+# Pipe-friendly: Language, file count, code, docs, empty, string
+pygount --format=summary . 2>/dev/null
+```
+
+## 6. Interpreting Results
+
+The summary table columns:
+- **Language** — detected programming language
+- **Files** — number of files of that language
+- **Code** — lines of actual code (executable/declarative)
+- **Comment** — lines that are comments or documentation
+- **%** — percentage of total
+
+Special pseudo-languages:
+- `__empty__` — empty files
+- `__binary__` — binary files (images, compiled, etc.)
+- `__generated__` — auto-generated files (detected heuristically)
+- `__duplicate__` — files with identical content
+- `__unknown__` — unrecognized file types
+
+## Pitfalls
+
+1. **Always exclude .git, node_modules, venv** — without `--folders-to-skip`, pygount will crawl everything and may take minutes or hang on large dependency trees.
+2. **Markdown shows 0 code lines** — pygount classifies all Markdown content as comments, not code. This is expected behavior.
+3. **JSON files show low code counts** — pygount may count JSON lines conservatively. For accurate JSON line counts, use `wc -l` directly.
+4. **Large monorepos** — for very large repos, consider using `--suffix` to target specific languages rather than scanning everything.

package/built-in-skills/prismer-computer-use/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/built-in-skills/prismer-computer-use/NOTICE.md

@@ -0,0 +1,17 @@
+# Resource provenance
+
+## Engineering adaptation (2026-09-23)
+
+Source: https://github.com/NousResearch/hermes-agent/tree/1a1f4a59e252e1dc0137e7b2e7bcc8b0381d19c4/skills/autonomous-ai-agents/computer-use
+
+Upstream authors: Francesco Bonacci (f-trycua), Hermes Agent.
+Hermes MIT copyright (c) 2025 Nous Research is preserved in LICENSE.
+All bundled references/templates/scripts remain covered by that notice unless
+an additional license is explicitly supplied. External CLI binaries, services,
+accounts and downloaded assets are not redistributed by this skill and retain
+their own terms. No API keys or third-party runtime packages are bundled.
+
+Prismer modifications: unique discovery/ownership mapping where applicable,
+resource-path and authorization corrections, bounded helpers, honest readiness
+and verification states. See docs/bugfix223/implementation-engineering.md in the
+source repository for resource mapping, tests and remaining live acceptance.