docs: add portable agent skills#873
Conversation
WalkthroughThis PR adds several new agent skill documentation sets: a ChangesHoncho CLI Skill
Honcho Integration Skill and Bot-Framework Reference
Python SDK Migration Guide
TypeScript SDK Migration Guide
Estimated code review effort: 2 (Simple) | ~15 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🧹 Nitpick comments (3)
.agents/skills/honcho-integration/references/bot-frameworks/nanobot/client.py (2)
36-79: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winSingleton silently ignores
configafter first initialization; no concurrency guard.Once
_honcho_clientis set (line 51-52), any subsequently-passedconfigis discarded without warning — a caller expecting to reconfigure (e.g. tests switching workspaces) gets the stale client instead. Also, the check-then-set on the module-level global (lines 51/73) has no lock, so concurrent first-time callers (common in async bot frameworks) can race and construct multipleHonchoclients.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/honcho-integration/references/bot-frameworks/nanobot/client.py around lines 36 - 79, Update get_honcho_client in client.py so it no longer silently reuses _honcho_client when a new config is passed; either reject differing config after initialization or make the singleton key/config-aware so callers don’t get a stale Honcho instance. Also add a concurrency guard around the _honcho_client check-and-create path (for example in get_honcho_client) to prevent multiple concurrent initializations from racing and creating duplicate Honcho clients.
63-69: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winChain the original
ImportError.Re-raising without
fromloses the original traceback context, making it harder for users of this reference implementation to diagnose whetherhoncho-aiis truly missing or another import failure occurred.🔧 Proposed fix
try: from honcho import Honcho - except ImportError: + except ImportError as err: raise ImportError( "honcho-ai is required for Honcho integration. " "Install it with: nanobot honcho enable --api-key YOUR_KEY" - ) + ) from err🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/honcho-integration/references/bot-frameworks/nanobot/client.py around lines 63 - 69, The Honcho import fallback in the client setup is re-raising a new ImportError without preserving the original exception context. Update the ImportError handling around the Honcho import so the raised ImportError chains the caught exception using the original exception object, keeping traceback context intact for the Honcho integration reference implementation.Source: Linters/SAST tools
.agents/skills/honcho-integration/references/bot-frameworks/nanobot/session.py (1)
419-427: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winMigration helpers silently no-op on cache miss instead of resolving the peer.
migrate_local_historyandmigrate_memory_filesboth do a rawself._peers_cache.get(user_peer_id)and bail out with a warning if the peer isn't already cached, rather than callingself._get_or_create_peer(user_peer_id)as every other method does. If the process restarted (or this session was never touched viaget_or_createin this process), migration silently does nothing even though the peer trivially could be resolved. The two blocks also duplicate the samechannel/chat_id/user_peer_idderivation logic — worth extracting into a shared helper.Also applies to: 514-521
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.agents/skills/honcho-integration/references/bot-frameworks/nanobot/session.py around lines 419 - 427, The migration helpers are skipping peer resolution on cache miss by using self._peers_cache.get(user_peer_id) and returning early, which makes migrate_local_history and migrate_memory_files no-op after restarts. Update both blocks to resolve the peer via self._get_or_create_peer(user_peer_id) instead of only checking the cache, and keep the warning/return only for real resolution failures. Also extract the repeated channel/chat_id/user_peer_id derivation in session.py into a shared helper so both migration paths use the same logic.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/honcho-cli/SKILL.md:
- Line 16: Update the Honcho CLI config documentation in SKILL.md to replace the
generic HONCHO_* scoping reference with the exact supported scope env vars:
HONCHO_WORKSPACE_ID, HONCHO_PEER_ID, and HONCHO_SESSION_ID. Keep the rest of the
config guidance intact, and ensure the per-command scope description matches the
CLI contract alongside the existing -w / -p / -s flags.
In
@.agents/skills/honcho-integration/references/bot-frameworks/nanobot/honcho_tool.py:
- Line 16: The Honcho tool constructor uses the HonchoSessionManager type
without importing it, so static analysis and navigation can’t resolve the
symbol. Update the honcho_tool.py reference implementation by adding the missing
HonchoSessionManager import in the appropriate place, or guard it with
TYPE_CHECKING if needed, and keep the __init__ annotation in HonchoTool
consistent with that imported symbol.
In
@.agents/skills/honcho-integration/references/bot-frameworks/nanobot/session.py:
- Around line 89-91: The unbounded in-memory state in HonchoSession is causing
long-lived growth because _cache, _peers_cache, and _sessions_cache never evict
entries. Update the HonchoSession initialization and related access paths to use
a bounded cache strategy with TTL, LRU, or a fixed size cap, and apply the same
treatment to the peer/session lookup logic in the affected methods around
HonchoSession so entries expire or are trimmed automatically. Ensure the cache
behavior remains keyed by session/user identifiers but cannot grow without
limit.
- Around line 336-357: get_user_context in session.py is making a blocking
Honcho request via user_peer.chat(query) inside an async tool path, which can
stall the event loop. Update this flow to use the async Honcho client path on
user_peer (such as aio.chat) or, if that is unavailable, offload the synchronous
chat call with asyncio.to_thread while preserving the existing error handling
and return behavior. Use the get_user_context and _get_or_create_peer symbols to
locate the change.
In @.agents/skills/honcho-integration/SKILL.md:
- Around line 313-317: The helper handle_honcho_tool_call currently promises a
str but directly returns peer.chat(query), which may be None. Update this
function to either normalize a safe string fallback before returning or widen
the return annotation to reflect the actual str | None behavior, and make sure
the implementation and type hint stay consistent with the peer.chat result.
In @.agents/skills/migrate-honcho-py/DETAILED-CHANGES.md:
- Around line 523-547: Update the documentation for peer() and session() to make
the created_at contract consistent across the migration guide and quick guide.
The issue is that this section says Peer/Session objects always populate
created_at immediately, while the quick guide still implies datetime | None.
Adjust the type/nullability wording in the relevant migration docs around
peer(), session(), and created_at so both sections agree and no longer conflict.
In @.agents/skills/migrate-honcho-ts/DETAILED-CHANGES.md:
- Around line 197-206: The `session.context()` example uses the wrong shape
because `searchQuery` is currently passed at the top level instead of inside
`representationOptions`. Update the example in `context()` so `searchQuery` is
nested under `representationOptions` alongside `maxConclusions` and
`includeMostFrequent`, and make sure the shown call matches the documented
migrated context structure.
In @.agents/skills/migrate-honcho-ts/SKILL.md:
- Around line 128-139: The representation example still passes the legacy
options bag directly into peer.representation(), but the migrated API expects
the renamed fields and rejects unknown ones. Update the example in the
representation section to explicitly translate maxObservations to maxConclusions
and includeMostDerived to includeMostFrequent before calling
peer.representation(), using the peer.representation symbol and the options
object shown in the snippet so upgrade users follow a validation-safe pattern.
---
Nitpick comments:
In
@.agents/skills/honcho-integration/references/bot-frameworks/nanobot/client.py:
- Around line 36-79: Update get_honcho_client in client.py so it no longer
silently reuses _honcho_client when a new config is passed; either reject
differing config after initialization or make the singleton key/config-aware so
callers don’t get a stale Honcho instance. Also add a concurrency guard around
the _honcho_client check-and-create path (for example in get_honcho_client) to
prevent multiple concurrent initializations from racing and creating duplicate
Honcho clients.
- Around line 63-69: The Honcho import fallback in the client setup is
re-raising a new ImportError without preserving the original exception context.
Update the ImportError handling around the Honcho import so the raised
ImportError chains the caught exception using the original exception object,
keeping traceback context intact for the Honcho integration reference
implementation.
In
@.agents/skills/honcho-integration/references/bot-frameworks/nanobot/session.py:
- Around line 419-427: The migration helpers are skipping peer resolution on
cache miss by using self._peers_cache.get(user_peer_id) and returning early,
which makes migrate_local_history and migrate_memory_files no-op after restarts.
Update both blocks to resolve the peer via
self._get_or_create_peer(user_peer_id) instead of only checking the cache, and
keep the warning/return only for real resolution failures. Also extract the
repeated channel/chat_id/user_peer_id derivation in session.py into a shared
helper so both migration paths use the same logic.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 856cb44b-f437-4481-ac3f-74ea8f6c44ff
📒 Files selected for processing (13)
.agents/skills/honcho-cli/SKILL.md.agents/skills/honcho-integration/SKILL.md.agents/skills/honcho-integration/references/bot-frameworks.md.agents/skills/honcho-integration/references/bot-frameworks/nanobot/client.py.agents/skills/honcho-integration/references/bot-frameworks/nanobot/honcho_tool.py.agents/skills/honcho-integration/references/bot-frameworks/nanobot/session.py.agents/skills/migrate-honcho-py/DETAILED-CHANGES.md.agents/skills/migrate-honcho-py/MIGRATION-CHECKLIST.md.agents/skills/migrate-honcho-py/SKILL.md.agents/skills/migrate-honcho-ts/DETAILED-CHANGES.md.agents/skills/migrate-honcho-ts/MIGRATION-CHECKLIST.md.agents/skills/migrate-honcho-ts/SKILL.md.claude/skills/migrate-honcho-py/SKILL.md
| - **TTY**: human-readable tables (default when interactive) | ||
| - **Piped / `--json`**: JSON — collection commands emit arrays, single-resource commands emit objects | ||
| - **Exit codes**: `0` success · `1` client error (bad input, not found) · `2` server error · `3` auth error | ||
| - **Config**: `~/.honcho/config.json` (shared with other Honcho tools). The CLI owns `apiKey` and `environmentUrl` at the top level; run `honcho init` to confirm or set them. Per-command scope (workspace / peer / session) is via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Spell out the exact scope env vars.
HONCHO_* is too broad here; the CLI contract only documents HONCHO_WORKSPACE_ID, HONCHO_PEER_ID, and HONCHO_SESSION_ID. Naming them explicitly avoids implying that other Honcho env vars are accepted for scoping.
Proposed fix
- - **Config**: `~/.honcho/config.json` (shared with other Honcho tools). The CLI owns `apiKey` and `environmentUrl` at the top level; run `honcho init` to confirm or set them. Per-command scope (workspace / peer / session) is via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars.
+ - **Config**: `~/.honcho/config.json` (shared with other Honcho tools). The CLI owns `apiKey` and `environmentUrl` at the top level; run `honcho init` to confirm or set them. Per-command scope (workspace / peer / session) is via `-w` / `-p` / `-s` flags or `HONCHO_WORKSPACE_ID` / `HONCHO_PEER_ID` / `HONCHO_SESSION_ID`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Config**: `~/.honcho/config.json` (shared with other Honcho tools). The CLI owns `apiKey` and `environmentUrl` at the top level; run `honcho init` to confirm or set them. Per-command scope (workspace / peer / session) is via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars. | |
| - **Config**: `~/.honcho/config.json` (shared with other Honcho tools). The CLI owns `apiKey` and `environmentUrl` at the top level; run `honcho init` to confirm or set them. Per-command scope (workspace / peer / session) is via `-w` / `-p` / `-s` flags or `HONCHO_WORKSPACE_ID` / `HONCHO_PEER_ID` / `HONCHO_SESSION_ID`. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.agents/skills/honcho-cli/SKILL.md at line 16, Update the Honcho CLI config
documentation in SKILL.md to replace the generic HONCHO_* scoping reference with
the exact supported scope env vars: HONCHO_WORKSPACE_ID, HONCHO_PEER_ID, and
HONCHO_SESSION_ID. Keep the rest of the config guidance intact, and ensure the
per-command scope description matches the CLI contract alongside the existing -w
/ -p / -s flags.
| based on their history and learned preferences. | ||
| """ | ||
|
|
||
| def __init__(self, session_manager: "HonchoSessionManager"): |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
HonchoSessionManager type is never imported — undefined name.
The string annotation "HonchoSessionManager" references a symbol that isn't imported anywhere in this file, not even under TYPE_CHECKING. This works at runtime only because it's a forward-reference string, but it breaks static type checkers and IDE navigation for anyone copying this reference implementation.
🔧 Proposed fix
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+ from nanobot.honcho.session import HonchoSessionManager
+
-from typing import Any
-
from nanobot.agent.tools.base import Tool🧰 Tools
🪛 Ruff (0.15.20)
[error] 16-16: Undefined name HonchoSessionManager
(F821)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.agents/skills/honcho-integration/references/bot-frameworks/nanobot/honcho_tool.py
at line 16, The Honcho tool constructor uses the HonchoSessionManager type
without importing it, so static analysis and navigation can’t resolve the
symbol. Update the honcho_tool.py reference implementation by adding the missing
HonchoSessionManager import in the appropriate place, or guard it with
TYPE_CHECKING if needed, and keep the __init__ annotation in HonchoTool
consistent with that imported symbol.
Source: Linters/SAST tools
| self._cache: dict[str, HonchoSession] = {} | ||
| self._peers_cache: dict[str, Any] = {} | ||
| self._sessions_cache: dict[str, Any] = {} |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Unbounded in-memory caches will grow indefinitely in a long-running bot process.
_cache, _peers_cache, and _sessions_cache (lines 89-91) accumulate one entry per unique user/session for the lifetime of the process with no eviction (TTL/LRU/size cap). For a bot serving many distinct users over time, this is an unbounded memory-growth path that can eventually lead to OOM. As reference code meant to be copied into production integrations, it's worth calling out and bounding.
Also applies to: 100-118
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.agents/skills/honcho-integration/references/bot-frameworks/nanobot/session.py
around lines 89 - 91, The unbounded in-memory state in HonchoSession is causing
long-lived growth because _cache, _peers_cache, and _sessions_cache never evict
entries. Update the HonchoSession initialization and related access paths to use
a bounded cache strategy with TTL, LRU, or a fixed size cap, and apply the same
treatment to the peer/session lookup logic in the affected methods around
HonchoSession so entries expire or are trimmed automatically. Ensure the cache
behavior remains keyed by session/user identifiers but cannot grow without
limit.
| def get_user_context(self, session_key: str, query: str) -> str: | ||
| """ | ||
| Query Honcho's dialectic chat for user context. | ||
|
|
||
| Args: | ||
| session_key: The session key to get context for. | ||
| query: Natural language question about the user. | ||
|
|
||
| Returns: | ||
| Honcho's response about the user. | ||
| """ | ||
| session = self._cache.get(session_key) | ||
| if not session: | ||
| return "No session found for this context." | ||
|
|
||
| user_peer = self._get_or_create_peer(session.user_peer_id) | ||
|
|
||
| try: | ||
| return user_peer.chat(query) | ||
| except Exception as e: | ||
| logger.error(f"Failed to get user context from Honcho: {e}") | ||
| return f"Unable to retrieve user context: {e}" |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== Relevant files ==\n'
git ls-files '.agents/skills/honcho-integration/references/bot-frameworks/nanobot/session.py' \
'.agents/skills/honcho-integration/references/bot-frameworks/nanobot/honcho_tool.py' \
'.agents/skills/honcho-integration/references/bot-frameworks/nanobot/client.py' \
'.agents/skills/honcho-integration/references/bot-frameworks/nanobot/*.py' \
| sed 's#^`#-` #'
printf '\n== Outline: session.py ==\n'
ast-grep outline .agents/skills/honcho-integration/references/bot-frameworks/nanobot/session.py --view expanded || true
printf '\n== Outline: honcho_tool.py ==\n'
ast-grep outline .agents/skills/honcho-integration/references/bot-frameworks/nanobot/honcho_tool.py --view expanded || true
printf '\n== Outline: client.py ==\n'
ast-grep outline .agents/skills/honcho-integration/references/bot-frameworks/nanobot/client.py --view expanded || true
printf '\n== Relevant lines from session.py ==\n'
sed -n '300,390p' .agents/skills/honcho-integration/references/bot-frameworks/nanobot/session.py | cat -n
printf '\n== Relevant lines from honcho_tool.py ==\n'
sed -n '1,180p' .agents/skills/honcho-integration/references/bot-frameworks/nanobot/honcho_tool.py | cat -n
printf '\n== Relevant lines from client.py ==\n'
sed -n '1,220p' .agents/skills/honcho-integration/references/bot-frameworks/nanobot/client.py | cat -n
printf '\n== Search for async client / aio / to_thread / execute() ==\n'
rg -n --hidden --glob '!**/.git/**' \
-e 'aio' \
-e 'asyncio\.to_thread' \
-e 'async def execute' \
-e 'user_peer\.chat\(' \
-e 'class .*Client' \
.agents/skills/honcho-integration/references/bot-frameworks/nanobot || trueRepository: plastic-labs/honcho
Length of output: 13429
🌐 Web query:
Honcho SDK async client aio chat method documentation
💡 Result:
In the Honcho Python SDK, asynchronous operations are accessed via the.aio accessor on the Honcho client and its derived objects (such as peers or sessions) [1][2]. To use the chat method asynchronously, you access it through the peer object's.aio namespace [1]. The following pattern is used: async def main: client = Honcho(api_key="your-api-key") # Accessing a peer asynchronously peer = await client.aio.peer("user-123") # Calling the chat method asynchronously response = await peer.aio.chat("Your query here") print(response) Key points: - The.aio accessor is available on the main Honcho client, as well as on peers and sessions [1]. - The async chat method supports the same parameters as the standard synchronous chat method, such as reasoning_level (e.g., 'minimal', 'low', 'medium', 'high', 'max') [3][1]. - This functionality enables integration into async-native Python environments like FastAPI or asyncio applications [1].
Citations:
- 1: https://pypi.org/project/honcho-ai/2.1.2/
- 2: https://pypi.org/project/honcho-ai/
- 3: https://honcho.dev/docs/v3/documentation/features/chat
Avoid the blocking Honcho call on the event loop — in .agents/skills/honcho-integration/references/bot-frameworks/nanobot/session.py:336-357, get_user_context() calls user_peer.chat(query) synchronously from an async tool path. That network request will block the event loop; switch to user_peer.aio.chat(query) or offload the sync call with asyncio.to_thread().
🧰 Tools
🪛 Ruff (0.15.20)
[warning] 355-355: Do not catch blind exception: Exception
(BLE001)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.agents/skills/honcho-integration/references/bot-frameworks/nanobot/session.py
around lines 336 - 357, get_user_context in session.py is making a blocking
Honcho request via user_peer.chat(query) inside an async tool path, which can
stall the event loop. Update this flow to use the async Honcho client path on
user_peer (such as aio.chat) or, if that is unavailable, offload the synchronous
chat call with asyncio.to_thread while preserving the existing error handling
and return behavior. Use the get_user_context and _get_or_create_peer symbols to
locate the change.
| def handle_honcho_tool_call(user_id: str, query: str) -> str: | ||
| """Execute the Honcho chat tool call.""" | ||
| peer = honcho.peer(user_id) | ||
| return peer.chat(query) | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Locate the relevant file and inspect the surrounding code.
git ls-files '.agents/skills/honcho-integration/SKILL.md'
wc -l .agents/skills/honcho-integration/SKILL.md
sed -n '280,340p' .agents/skills/honcho-integration/SKILL.md
# Find any references to honcho.peer and peer.chat usage/types in the repo.
rg -n "honcho\.peer\(|peer\.chat\(" -S .
rg -n "class .*Honcho|def chat\(|chat\(.*\) ->" -S .Repository: plastic-labs/honcho
Length of output: 45027
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the package metadata to identify the Honcho SDK dependency/version if present.
rg -n "honcho|Honcho" -S pyproject.toml requirements*.txt poetry.lock uv.lock Pipfile* setup.cfg setup.py . 2>/dev/null || trueRepository: plastic-labs/honcho
Length of output: 50376
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# If the SDK is vendored or stubbed locally, inspect likely type files only.
fd -a -t f "honcho" . 2>/dev/null || true
fd -a -t f "peer" . 2>/dev/null || trueRepository: plastic-labs/honcho
Length of output: 5477
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the Python SDK peer.chat implementation and its return annotations.
wc -l sdks/python/src/honcho/peer.py
sed -n '200,300p' sdks/python/src/honcho/peer.py
# Also inspect the async client surface if peer.chat delegates there.
wc -l sdks/python/src/honcho/aio.py
sed -n '560,640p' sdks/python/src/honcho/aio.pyRepository: plastic-labs/honcho
Length of output: 8013
Handle peer.chat() returning None. This helper is annotated -> str, but peer.chat() can return str | None; widen the return type or normalize a fallback before returning.
🧰 Tools
🪛 SkillSpector (2.3.7)
[error] 175: [E2] Env Variable Harvesting: Code accesses environment variables that may contain secrets (API keys, tokens). This is a common pattern for credential theft.
Remediation: Avoid reading sensitive env vars (API keys, tokens) unless strictly required. Use secrets managers or secure config. Never log or transmit credentials.
(Data Exfiltration (E2))
[error] 292: [E2] Env Variable Harvesting: Code accesses environment variables that may contain secrets (API keys, tokens). This is a common pattern for credential theft.
Remediation: Avoid reading sensitive env vars (API keys, tokens) unless strictly required. Use secrets managers or secure config. Never log or transmit credentials.
(Data Exfiltration (E2))
[warning] 86: [RA2] Session Persistence: Skill establishes unauthorized persistence across sessions via cron jobs, startup scripts, or state files. Session persistence allows an attacker to maintain access beyond the current interaction.
Remediation: Remove any persistence mechanisms (cron jobs, startup scripts, state files). Skills should not maintain state across sessions without explicit user consent.
(Rogue Agent (RA2))
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.agents/skills/honcho-integration/SKILL.md around lines 313 - 317, The
helper handle_honcho_tool_call currently promises a str but directly returns
peer.chat(query), which may be None. Update this function to either normalize a
safe string fallback before returning or widen the return annotation to reflect
the actual str | None behavior, and make sure the implementation and type hint
stay consistent with the peer.chat result.
| ## 16. peer() and session() Always Make API Calls (v2.1.0) | ||
|
|
||
| ### Before (v2.0.x) | ||
|
|
||
| ```python | ||
| # Without options: lazy object, no API call | ||
| peer = client.peer("user-123") | ||
| # peer.created_at was None | ||
|
|
||
| # With options: made API call | ||
| peer = client.peer("user-123", metadata={"key": "value"}) | ||
| ``` | ||
|
|
||
| ### After (v2.1.0+) | ||
|
|
||
| ```python | ||
| # Always makes a get-or-create API call | ||
| peer = client.peer("user-123") | ||
| # peer.created_at is now always populated | ||
|
|
||
| # Async | ||
| peer = await client.aio.peer("user-123") | ||
| ``` | ||
|
|
||
| All Peer/Session objects now have `created_at` populated immediately after construction. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Reconcile the created_at contract.
This section says peer.created_at / session.created_at are always populated, but the quick guide still documents them as datetime | None. Please align the two docs so migration readers don't get conflicting nullability guidance.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.agents/skills/migrate-honcho-py/DETAILED-CHANGES.md around lines 523 - 547,
Update the documentation for peer() and session() to make the created_at
contract consistent across the migration guide and quick guide. The issue is
that this section says Peer/Session objects always populate created_at
immediately, while the quick guide still implies datetime | None. Adjust the
type/nullability wording in the relevant migration docs around peer(),
session(), and created_at so both sections agree and no longer conflict.
| const ctx = await session.context({ | ||
| summary: true, | ||
| peerTarget: user, | ||
| peerPerspective: assistant, | ||
| searchQuery: "What are my preferences?", | ||
| representationOptions: { | ||
| maxConclusions: 50, | ||
| includeMostFrequent: true | ||
| } | ||
| }) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Locate the relevant files and inspect the surrounding documentation.
git ls-files '.agents/skills/migrate-honcho-ts/DETAILED-CHANGES.md' '.agents/skills/migrate-honcho-ts/SKILL.md'
printf '\n--- DETAILED-CHANGES outline ---\n'
wc -l .agents/skills/migrate-honcho-ts/DETAILED-CHANGES.md
printf '\n--- SKILL outline ---\n'
wc -l .agents/skills/migrate-honcho-ts/SKILL.md
printf '\n--- DETAILED-CHANGES lines 180-230 ---\n'
sed -n '180,230p' .agents/skills/migrate-honcho-ts/DETAILED-CHANGES.md
printf '\n--- search for searchQuery usage in skill docs ---\n'
rg -n "searchQuery|representationOptions" .agents/skills/migrate-honcho-ts/DETAILED-CHANGES.md .agents/skills/migrate-honcho-ts/SKILL.mdRepository: plastic-labs/honcho
Length of output: 3012
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the exact migration examples and any API-shape notes in the skill docs.
printf '\n--- SKILL.md lines around searchQuery mentions ---\n'
grep -n -C 3 -E 'searchQuery|representationOptions|context\(' .agents/skills/migrate-honcho-ts/SKILL.md || true
printf '\n--- DETAILED-CHANGES.md lines around the commented snippet ---\n'
sed -n '190,215p' .agents/skills/migrate-honcho-ts/DETAILED-CHANGES.mdRepository: plastic-labs/honcho
Length of output: 2696
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'FILES\n'
git ls-files '.agents/skills/migrate-honcho-ts/DETAILED-CHANGES.md' '.agents/skills/migrate-honcho-ts/SKILL.md'
printf '\nDETAILED-CHANGES around lines 190-215\n'
sed -n '190,215p' .agents/skills/migrate-honcho-ts/DETAILED-CHANGES.md
printf '\nSKILL mentions\n'
grep -n -C 3 -E 'searchQuery|representationOptions|context\(' .agents/skills/migrate-honcho-ts/SKILL.md || trueRepository: plastic-labs/honcho
Length of output: 2736
Move searchQuery under representationOptions in this example. The snippet should match the documented context() shape.
Correct the migrated context shape.
const ctx = await session.context({
summary: true,
peerTarget: user,
peerPerspective: assistant,
- searchQuery: "What are my preferences?",
representationOptions: {
+ searchQuery: "What are my preferences?",
maxConclusions: 50,
includeMostFrequent: true
}
})📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const ctx = await session.context({ | |
| summary: true, | |
| peerTarget: user, | |
| peerPerspective: assistant, | |
| searchQuery: "What are my preferences?", | |
| representationOptions: { | |
| maxConclusions: 50, | |
| includeMostFrequent: true | |
| } | |
| }) | |
| const ctx = await session.context({ | |
| summary: true, | |
| peerTarget: user, | |
| peerPerspective: assistant, | |
| representationOptions: { | |
| searchQuery: "What are my preferences?", | |
| maxConclusions: 50, | |
| includeMostFrequent: true | |
| } | |
| }) |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.agents/skills/migrate-honcho-ts/DETAILED-CHANGES.md around lines 197 - 206,
The `session.context()` example uses the wrong shape because `searchQuery` is
currently passed at the top level instead of inside `representationOptions`.
Update the example in `context()` so `searchQuery` is nested under
`representationOptions` alongside `maxConclusions` and `includeMostFrequent`,
and make sure the shown call matches the documented migrated context structure.
| ### 9. Update representation calls | ||
|
|
||
| ```typescript | ||
| // Before | ||
| const rep = await peer.workingRep(session, target, options) | ||
| console.log(rep.explicit) // ExplicitObservation[] | ||
| console.log(rep.deductive) // DeductiveObservation[] | ||
|
|
||
| // After | ||
| const rep = await peer.representation({ session, target, ...options }) | ||
| console.log(rep) // string | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Map the guide structure and locate the referenced section.
git ls-files '.agents/skills/migrate-honcho-ts/SKILL.md'
wc -l .agents/skills/migrate-honcho-ts/SKILL.md
sed -n '1,220p' .agents/skills/migrate-honcho-ts/SKILL.md
# Find the option rename and strict-validation sections mentioned in the review comment.
rg -n "maxObservations|maxConclusions|includeMostDerived|includeMostFrequent|strict|validation|unknown options|representation\\(" .agents/skills/migrate-honcho-ts/SKILL.mdRepository: plastic-labs/honcho
Length of output: 6868
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the representation section around the cited lines.
sed -n '120,150p' .agents/skills/migrate-honcho-ts/SKILL.md
# Inspect the appendix table that maps old to new APIs/options.
sed -n '248,276p' .agents/skills/migrate-honcho-ts/SKILL.mdRepository: plastic-labs/honcho
Length of output: 2156
Map the legacy option names before representation()
This example still forwards the old options bag unchanged, but the migration table already renames maxObservations → maxConclusions and includeMostDerived → includeMostFrequent, and strict validation rejects unknown fields. Show the translated object here so upgrade users don’t hit a validation error.
Fix the example to translate the renamed fields explicitly.
-const rep = await peer.representation({ session, target, ...options })
+const rep = await peer.representation({
+ session,
+ target,
+ searchQuery: options?.searchQuery,
+ maxConclusions: options?.maxObservations,
+ includeMostFrequent: options?.includeMostDerived,
+})📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### 9. Update representation calls | |
| ```typescript | |
| // Before | |
| const rep = await peer.workingRep(session, target, options) | |
| console.log(rep.explicit) // ExplicitObservation[] | |
| console.log(rep.deductive) // DeductiveObservation[] | |
| // After | |
| const rep = await peer.representation({ session, target, ...options }) | |
| console.log(rep) // string | |
| ``` | |
| ### 9. Update representation calls | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.agents/skills/migrate-honcho-ts/SKILL.md around lines 128 - 139, The
representation example still passes the legacy options bag directly into
peer.representation(), but the migrated API expects the renamed fields and
rejects unknown ones. Update the example in the representation section to
explicitly translate maxObservations to maxConclusions and includeMostDerived to
includeMostFrequent before calling peer.representation(), using the
peer.representation symbol and the options object shown in the snippet so
upgrade users follow a validation-safe pattern.
1 participant
Goal
Add a portable
.agents/skills/directory that mirrors the existing.claude/skills/Honcho skills, so agent workflows are no longer tied only to Claude-specific skill discovery.Why This Helps
Many coding agents like codex, opencode, omp etc. recognize
.agents/skills/as the shared convention for project-scopedagent skills.This will help fast-track developers using coding agents other than claude code during their dev phases.
keeps the current Claude setup intact while adding a cross-agent path for reuse.
Summary by CodeRabbit