Improve Pinet tool guidance and system append context

[gugu91]

Summary

Improve Pinet tool ergonomics for agents by making dispatcher args usage and Pinet inbox pointer semantics clear in system guidance, and consider surfacing the args object requirement more directly in tool/help schema output.

Observed feedback

Broker/worker agents can easily misuse the compact pinet dispatcher from fresh context:

1. The local tool surface appears compact (action-driven), but most actions require an args object. A first attempt such as pinet action=read can fail with an input error like args must be an object for Pinet action execution. Pass a JSON object as args. The fix is to call, for example, pinet action=read args={ thread_id, unread_only, ... }, but that may only become obvious after failure/help output.
2. The message pointer format is token-efficient (pointer=pinet action=read args.thread_id=... args.unread_only=true) but not self-explanatory to a fresh agent. Agents should understand that these are durable Pinet inbox pointers and how to read/mark/reply.
3. Agents would benefit from a concise Pinet primer in the system append: Pinet as the agent mesh/durable inbox, common actions (read, send, agents, lanes, free, schedule, ports), expected args shape, unread/read semantics, and reply routing expectations.

Maintainer request: “can you please file an issue with feedback you have for the tools not working? I think we should also have a system append that describes pinet a bit” and “probably formalise your feedback and get a worker on it”.

Suggested changes

• Add or update a system append / injected guidance section for Pinet-enabled agents with a concise primer covering:
  • what Pinet is (agent mesh + durable inbox)
  • how to read compact pointers (pinet action=read args.thread_id=... args.unread_only=true)
  • that dispatcher action parameters must be passed under args
  • common actions and reply-routing expectations
  • unread/read/mark-read behavior
• Consider making dispatcher schema/help/error text expose the args object requirement more clearly so first calls fail less often.
• Keep guidance compact and consistent with the repo’s token-efficient progressive-discovery pattern.

Acceptance criteria

• File and track this issue for the extensions repo.
• If implemented, agents receive a concise Pinet primer/system append when the Pinet tools/context are active.
• Pinet dispatcher docs/help make args usage clear without expanding every action schema into the always-loaded prompt.
• Tests/docs are updated where appropriate.
• Appropriate package validation passes.
• If code/docs changes are made, open a PR linked to this issue.

Notes

• Avoid exposing secrets, raw private prompt bodies, raw broker DB internals, or sensitive paths in user-visible Slack/Pinet/GitHub output.