Skip to content

feat(core): ContentPart + parts() helper for multi-format result envelopes#115

Merged
vreshch merged 2 commits into
masterfrom
feature/result-content-parts
Apr 26, 2026
Merged

feat(core): ContentPart + parts() helper for multi-format result envelopes#115
vreshch merged 2 commits into
masterfrom
feature/result-content-parts

Conversation

@vreshch
Copy link
Copy Markdown
Member

@vreshch vreshch commented Apr 26, 2026

Summary

Formalizes the convention surfaced during the admin-agents UX walk: the final `result` event can carry multiple MIME-typed views of the same output. Order = render preference.

```ts
import { result, parts } from '@agentage/core';

yield result(true, parts({
markdown: '# Done\n\n42 commits',
json: { commits: 42 },
}));
```

Backward compatible — `result(success, output?: unknown)` still accepts any value.

API additions

  • `ContentPart` type: `{ type: string; content: unknown }`
  • `ResultOutput` alias: `unknown` (with docs explaining the array convention)
  • `parts({ markdown, text, json, extra })` factory — builds a `ContentPart[]` in canonical preference order

Canonical MIME types: `text/markdown` → `text/plain` → `application/json`. Non-canonical parts pass through `extra`.

Bumps `@agentage/core` to 0.10.0 (minor — additive only).

Cross-repo follow-ups

  • `agentage/web#235` (in flight) — `ResultEvent` detects array-of-parts, renders preferred view with JSON toggle.
  • `agentage/agents#5` (in flight) — 5 TS agents emit `result(true, parts({...}))`.

Test plan

  • `npm run verify` green (151 tests pass, including 6 new tests for `parts()` + ContentPart)
  • Existing `result()` callers in CLI / hub / e2e remain green (no signature change)

… envelopes

Formalizes the convention surfaced during the admin-agents UX walk: the
final result event can carry multiple MIME-typed views of the same
output. Order in the array signals render preference. Backward
compatible — `result(success, output?: unknown)` still accepts any value.

API additions (no signature changes):
- `ContentPart` type — `{ type: string; content: unknown }`
- `ResultOutput` type — alias for `unknown` with docs
- `parts({ markdown, text, json, extra })` factory — builds a
  ContentPart[] in canonical preference order

Canonical types: `text/markdown` → `text/plain` → `application/json`.
Anything else passes through `extra`.

Cross-repo follow-ups:
- web/dashboard ResultEvent: detect array-of-parts, render preferred
  view + JSON toggle (in flight: agentage/web#235)
- agents: emit `result(true, parts({ markdown, json }))` on the 5 TS
  agents (in flight: agentage/agents#5)

Bumps @agentage/core to 0.10.0 (minor — additive).
@vreshch vreshch marked this pull request as ready for review April 26, 2026 18:05
@vreshch vreshch merged commit 20d2f67 into master Apr 26, 2026
2 checks passed
@vreshch vreshch deleted the feature/result-content-parts branch April 26, 2026 18:06
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Apr 26, 2026

🎉 PR Validation ✅ PASSED

Commit: 7c86257f897bf091d5be672a1756ef5b10cb0ce6
Branch: feature/result-content-parts

Checks:

  • ✅ Release guard (no version/changelog changes)
  • ✅ Dependencies installed
  • ✅ Type check passed
  • ✅ Linting passed
  • ✅ Format check passed
  • ✅ Tests + coverage passed
  • ✅ Build successful

Ready to merge!


🔗 View workflow run
⏰ Generated at: 2026-04-26T18:06:51.620Z

vreshch added a commit that referenced this pull request Apr 26, 2026
Re-publish: 0.10.0 on npm pre-dates ContentPart + parts() from #115.
0.10.1 picks up the new exports.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant