docs: refresh recent behavior notes by poe-code-agent[bot] · Pull Request #262 · poe-platform/poe-code

poe-code-agent · 2026-04-29T00:33:28Z

Summary

Document recent provider behavior: provider login --base-url, shape-specific endpoint storage, required Cloudflare gateway URLs, and freeform provider model handling.
Refresh Codex E2E assertion docs for the active top-level model defaults, profile values, and current Poe API base URL.
Keep the existing package README refreshes on this documentation branch for task-list, harness, telemetry, agent-spawn, workflow, config, and Toolcraft behavior.

Verification

Reviewed the 8 commits that landed on origin/main in the last 24 hours as of 2026-05-23 UTC.
Verified documentation claims against src/cli/commands/provider.ts, src/cli/commands/shared.ts, packages/providers/src/providers/cloudflare.ts, src/templates/codex/config.toml.mustache, src/cli/constants.ts, and packages/providers/src/providers/poe.ts.
npx prettier --check packages/providers/README.md
git diff --check origin/main...HEAD

poe-code-agent

LGTM

poe-code-agent

LGTM

poe-code-agent

Requested changes: one Toolcraft CLI help note contradicts current output.

poe-code-agent

Requested changes: Toolcraft help docs still contradict positional rendering.

poe-code-agent · 2026-05-04T00:30:03Z


 **Tree**: the `root` group is a `defineGroup` whose children are commands and sub-groups. Any depth. CLI flags, MCP tool names, and SDK methods are derived from the path.

+**CLI help**: group help lists visible child commands with their parameter tokens inline. Required options appear as `--name <type>`, optional options and defaults appear in brackets like `[--limit <number>]`, and positional parameters stay unbracketed even when the underlying schema field is optional. Command-specific `--help` still shows the detailed parameter table.


This still contradicts the current formatter: formatHelpFieldFlags() uses formatPositionalToken() for positional fields, and formatPositionalToken() wraps optional/default positionals in brackets (for example [agent]).

Suggested change

**CLI help**: group help lists visible child commands with their parameter tokens inline. Required options appear as `--name <type>`, optional options and defaults appear in brackets like `[--limit <number>]`, and positional parameters stay unbracketed even when the underlying schema field is optional. Command-specific `--help` still shows the detailed parameter table.

**CLI help**: group help lists visible child commands with their parameter tokens inline. Required options appear as `--name <type>`, optional options and defaults appear in brackets like `[--limit <number>]`, and positional parameters render as `<name>` or `[name]` depending on whether the underlying schema field is required. Command-specific `--help` still shows the detailed parameter table.

poe-code-agent

LGTM

poe-code-agent

Requested changes: public API docs list non-exported behavior.

poe-code-agent · 2026-05-16T00:34:25Z

+
+## Trace shape
+
+`acpToTrace` creates one root `agent:<agent>:<model>` span with redacted prompt input, accumulated assistant output, token/cost/duration metrics when present, session/thread metadata, and one child span per ACP tool call. Tool child spans include redacted inputs, assembled tool outputs, tool call metadata, and start/end timestamps when the ACP event metadata includes them.


acpToTrace does not currently include any cost metric from ctx.usage (it only maps token counts/cache counts and durationMs in buildMetrics), so documenting cost here is misleading.

Suggested change

`acpToTrace` creates one root `agent:<agent>:<model>` span with redacted prompt input, accumulated assistant output, token/cost/duration metrics when present, session/thread metadata, and one child span per ACP tool call. Tool child spans include redacted inputs, assembled tool outputs, tool call metadata, and start/end timestamps when the ACP event metadata includes them.

`acpToTrace` creates one root `agent:<agent>:<model>` span with redacted prompt input, accumulated assistant output, token/duration metrics when present, session/thread metadata, and one child span per ACP tool call. Tool child spans include redacted inputs, assembled tool outputs, tool call metadata, and start/end timestamps when the ACP event metadata includes them.

poe-code-agent · 2026-05-16T00:34:25Z

+- `listBuiltinTemplates()` returns bundled template pairs: `ralph-demo`, `coverage-demo`, `experiment-demo`, `pipeline-demo`, and `superintendent-demo`.
+- `extractSchema(source, filename)` reads a harness script's exported schema for frontmatter validation.
+- `resolvePair(mdPath)` resolves the Markdown/script pair for a harness document.
+- `LintError` wraps lint diagnostics raised before execution.


LintError is declared in loader/run.ts, but packages/agent-harness/src/index.ts does not re-export it and the package only exports dist/index.js. Either export it from the public entrypoint or drop this public API bullet.

Co-authored-by: poe-code-agent[bot] <254571472+poe-code-agent[bot]@users.noreply.github.com>

poe-code-agent

Requested changes: docs still describe behavior/API that is not present.

poe-code-agent · 2026-05-23T00:40:02Z

+
+## Trace shape
+
+`acpToTrace` creates one root `agent:<agent>:<model>` span with redacted prompt input, accumulated assistant output, token/cost/duration metrics when present, session/thread metadata, and one child span per ACP tool call. Tool child spans include redacted inputs, assembled tool outputs, tool call metadata, and start/end timestamps when the ACP event metadata includes them.


acpToTrace still does not emit a cost metric: buildMetrics() maps token counts/cache counts and durationMs, but not costUsd/cost. Keeping cost here makes the trace contract inaccurate.

Suggested change

`acpToTrace` creates one root `agent:<agent>:<model>` span with redacted prompt input, accumulated assistant output, token/cost/duration metrics when present, session/thread metadata, and one child span per ACP tool call. Tool child spans include redacted inputs, assembled tool outputs, tool call metadata, and start/end timestamps when the ACP event metadata includes them.

`acpToTrace` creates one root `agent:<agent>:<model>` span with redacted prompt input, accumulated assistant output, token/duration metrics when present, session/thread metadata, and one child span per ACP tool call. Tool child spans include redacted inputs, assembled tool outputs, tool call metadata, and start/end timestamps when the ACP event metadata includes them.

poe-code-agent · 2026-05-23T00:40:02Z

+- `listBuiltinTemplates()` returns bundled template pairs: `ralph-demo`, `coverage-demo`, `experiment-demo`, `pipeline-demo`, and `superintendent-demo`.
+- `extractSchema(source, filename)` reads a harness script's exported schema for frontmatter validation.
+- `resolvePair(mdPath)` resolves the Markdown/script pair for a harness document.
+- `LintError` wraps lint diagnostics raised before execution.


LintError is still not exported from packages/agent-harness/src/index.ts, and the package only exposes that entrypoint. Please either export it or remove it from the documented public API.

poe-code-agent · 2026-05-23T00:40:02Z

+`openPlanList`, `discoverPlans`, and `archivePlan` expose numbered Markdown plan folders through `@poe-code/task-list`. They resolve the configured plan directory with the same cwd/home rules as workflow docs, open it as a `markdown-dir` single-list named `plans`, and use `frontmatterMode: "passthrough"` so plan-specific metadata survives task updates.
+
+- `discoverPlans({ cwd, homeDir, planDirectory, kinds? })` returns plan ids, names, kinds, absolute paths, and display paths. Numeric filename prefixes such as `04-api-shape-providers.md` are stripped from ids.
+- `archivePlan({ cwd, homeDir, planDirectory, id })` fires the task-list `archive` event, moves the document under `archive/`, and repacks active plan prefixes.


archivePlan() does not repack active prefixes; the current test explicitly expects archiving to leave 01-first.md and 03-third.md in place.

Suggested change

- `archivePlan({ cwd, homeDir, planDirectory, id })` fires the task-list `archive` event, moves the document under `archive/`, and repacks active plan prefixes.

- `archivePlan({ cwd, homeDir, planDirectory, id })` fires the task-list `archive` event and moves the document under `archive/` without renumbering active plan prefixes.

poe-code-agent Bot force-pushed the agent/update-documentation branch from 1846751 to 1717f39 Compare April 29, 2026 00:33

poe-code-agent Bot commented Apr 29, 2026

View reviewed changes

poe-code-agent Bot force-pushed the agent/update-documentation branch from 1717f39 to 021fc50 Compare May 1, 2026 00:31

poe-code-agent Bot changed the title ~~docs: document toolcraft group help parameters~~ docs: refresh recent behavior notes May 1, 2026

poe-code-agent Bot commented May 1, 2026

View reviewed changes

Comment thread packages/toolcraft/README.md Outdated

poe-code-agent Bot force-pushed the agent/update-documentation branch from 021fc50 to 888fc84 Compare May 4, 2026 00:27

poe-code-agent Bot commented May 4, 2026

View reviewed changes

poe-code-agent Bot force-pushed the agent/update-documentation branch from 1e78578 to bb293d4 Compare May 14, 2026 00:33

poe-code-agent Bot commented May 14, 2026

View reviewed changes

poe-code-agent Bot force-pushed the agent/update-documentation branch from bb293d4 to c6fa8e6 Compare May 16, 2026 00:31

poe-code-agent Bot commented May 16, 2026

View reviewed changes

poe-code-agent Bot and others added 7 commits May 23, 2026 00:32

docs: document toolcraft group help parameters

f0c0781

docs: update provider and goose auth notes

d9e72ee

docs: document config self-discovery handling

61d49ad

Apply suggestions from code review

bbaec28

Co-authored-by: poe-code-agent[bot] <254571472+poe-code-agent[bot]@users.noreply.github.com>

docs: document github workflow run failures

096bb68

docs: document recent package behavior

a69370d

docs: document recent provider configuration changes

815a869

poe-code-agent Bot force-pushed the agent/update-documentation branch from c6fa8e6 to 815a869 Compare May 23, 2026 00:36

poe-code-agent Bot commented May 23, 2026

View reviewed changes


		Tree: the `root` group is a `defineGroup` whose children are commands and sub-groups. Any depth. CLI flags, MCP tool names, and SDK methods are derived from the path.

		CLI help: group help lists visible child commands with their parameter tokens inline. Required options appear as `--name <type>`, optional options and defaults appear in brackets like `[--limit <number>]`, and positional parameters stay unbracketed even when the underlying schema field is optional. Command-specific `--help` still shows the detailed parameter table.


		## Trace shape

		`acpToTrace` creates one root `agent:<agent>:<model>` span with redacted prompt input, accumulated assistant output, token/cost/duration metrics when present, session/thread metadata, and one child span per ACP tool call. Tool child spans include redacted inputs, assembled tool outputs, tool call metadata, and start/end timestamps when the ACP event metadata includes them.

	- `archivePlan({ cwd, homeDir, planDirectory, id })` fires the task-list `archive` event, moves the document under `archive/`, and repacks active plan prefixes.
	- `archivePlan({ cwd, homeDir, planDirectory, id })` fires the task-list `archive` event and moves the document under `archive/` without renumbering active plan prefixes.

Conversation

poe-code-agent Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Uh oh!

poe-code-agent Bot left a comment

Choose a reason for hiding this comment

Uh oh!

poe-code-agent Bot left a comment

Choose a reason for hiding this comment

Uh oh!

poe-code-agent Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

poe-code-agent Bot left a comment

Choose a reason for hiding this comment

Uh oh!

poe-code-agent Bot May 4, 2026

Choose a reason for hiding this comment

Uh oh!

poe-code-agent Bot left a comment

Choose a reason for hiding this comment

Uh oh!

poe-code-agent Bot left a comment

Choose a reason for hiding this comment

Uh oh!

poe-code-agent Bot May 16, 2026

Choose a reason for hiding this comment

Uh oh!

poe-code-agent Bot May 16, 2026

Choose a reason for hiding this comment

Uh oh!

poe-code-agent Bot left a comment

Choose a reason for hiding this comment

Uh oh!

poe-code-agent Bot May 23, 2026

Choose a reason for hiding this comment

Uh oh!

poe-code-agent Bot May 23, 2026

Choose a reason for hiding this comment

Uh oh!

poe-code-agent Bot May 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

poe-code-agent Bot commented Apr 29, 2026 •

edited

Loading