feat(agents): bound internal read-only helper execution

[decode2]

Linked issue

Refs #1702 (approved). Internal execution core only; public reasoning/permission and owner decisions follow later.

Stack

After #1734. Base test/1702-consultation-sdk. Chain #1714 → #1715 → #1720 → #1724 → #1729 → #1733 → #1734 → this PR.

PR type

• New feature (type:feature)

Summary

• Add internal one-run read-only SDK stream engine over a nested whitelist of captured published facts and one explicit question.
• Bound local input/output/deadline, preserve one in-flight lease until actual provider settlement, link caller abort and current-source checks, and never retry.
• Return sanitized helper advice, actual/requested model identities and finite usage without tools, owner wakeups, private context or authority.

Changes

Path	Change
lib/orchestrator-helper.ts	Bounded single-stream execution, snapshot projection, cancellation/lease and non-authority
tests/orchestrator-helper.test.ts	Seven deterministic stream cases including ignored abort/late rejection/concurrency/privacy/bounds
Docs and ODD tracker	Contract, real evidence and next-unit permission obligations

Test plan

• Meaningful concurrency RED invoked two streams (undefined !== busy); GREEN7/7.
• Helper plus consultation/state/catalog/discovery/presence/agents suite:214 pass,0 fail.
• Unchanged actual metadata SDK fixture:1 pass; this is NOT nested-helper SDK proof.
• node scripts/check-types.mjs:186baseline diagnostics,no regressions (not clean compilation); initial4new diagnostics were fixed.
• node scripts/build-runtime-modules.mjs --check:8modules match; git diff --check.
• Assessment:385lines,medium,runtime large writer,underbudget; self-verification stands,no separate verifier required. Native outcome unknown,not closed.

Hard boundaries

16KiB total input including static prompt,1024UTF8B question,512 requested output tokens,4096B returned text,20-second local deadline. Context contains no tools or private history; toolChoice:none, maxRetries:0. Provider output tool calls are rejected, never executed; thought/error content is not exported. Currentness failure/cancellation discards output; no automatic retries.

Abort and token ceilings are SDK requests, not guaranteed remote billing caps. A provider ignoring abort keeps the engine busy until its actual result settles. No timer/late rejection releases the lease prematurely. Usage is numeric-whitelisted, not model-authored permissions.

All output is helper_advice, ownerReply:false, authority:none, even if model text claims consent. This internal engine grants NO model-cost authorization. Public reasoning is still disabled; next tool integration requires real human UI opt-in. Messaging grants and metadata notes cannot grant that permission.

Contributor checklist

• Approved issue linked nonclosing; exactly one selected type label.
• Code/tests/docs included,conventional commit,no attribution trailers.
• Shellcheck/skill checks not applicable.
• Remote checks pending after publication.

No paid/outbound model calls were used in tests. No merge,auto-merge or runtime reload authorized.

Summary by CodeRabbit

• New Features
  • Added a read-only advisory feature that can provide responses to explicit questions using published information. Advice is non-authoritative and is not generated automatically.
  • Requests are bounded by input and response limits, and unavailable outcomes are returned for invalid, stale, or failed requests.
• Documentation
  • Clarified that use requires explicit human opt-in and that SDK fixture results do not demonstrate nested-helper execution.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: c27776d5-70f1-445a-9572-e10fc0ddb961

📥 Commits

Reviewing files that changed from the base of the PR and between 7f55a9f and 3b59622.

📒 Files selected for processing (4)

• docs/gentle-agents-activity.md
• lib/orchestrator-helper.ts
• odd/tasks/agent-coordination.md
• tests/orchestrator-helper.test.ts

 __________________________________________________
< Your stack overflowed; I brought a bigger stack. >
 --------------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}