refactor: unify result types with discriminated Result<T, E> union

[Hweinstock]

Description

Problem

The codebase uses an inconsistent result-like type that changes depending on the context. The implementations vary slightly, and are not explicit about (usually) sharing a common shape. This common shape also strips error types, and distills their information down to a string, which leads to brittle behavior when catching errors.

As an example, systems that span modules (ex. telemetry) must handle each result type individually, resulting in excessive branching and complexity. Additionally, loss of error information, means loss of this information in telemetry, making it difficult to impossible to tell the type of error, and if it was user/application caused.

Solution

• unify result types behind a common flexible interface loosely based on Rust results. The main difference is that data is hoisted to the top level to be consistent with existing patterns.
• store full error information on the result, allowing for instanceof checking and error name matching for stronger exception handling and telemetry.

Future Work

There are other result types that could be generalized with further work to support spread operators on the error as well. I left this OOS since the PR is already very large. Some other small patterns that this PR continues, but I think should change in the future:

• excessive mocking (Ex. some tests mock entire modules, rather than the underlying dependencies. We mock our own code in some places).
• testing implementation rather than behavior (error messages are matches verbatim in many places, likely because thats all we had before. However, we should change these tests the verify error "shape" rather than exact content.
• higher level utilities for working with results. There are common patterns that could be useful to abstract. As an example, a mapResult function that allows data transformations with clear error propagation. This could avoid some nesting of try/catches in a few places.
• add more error types as we see fit.
• avoid using console.log directly for more flexibility.

Related Issue

Closes #

Documentation PR

N/A — internal refactor, no user-facing changes.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe): Internal refactor — unify result types

Testing

How have you tested the change?

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	43.09%	9025 / 20942
🔵	Statements	42.38%	9583 / 22612
🔵	Functions	39.97%	1559 / 3900
🔵	Branches	39.94%	5808 / 14540

Generated in workflow #2559 for commit eea25e4 by the Vitest Coverage Report Action

[padmak30]

Bug Bash Report — refactor: unify result types with discriminated Result<T, E> union

Branch: refactor/unified-result-type-v2 | Version: 0.13.0 | Base: main

TL;DR

No in-scope blockers, highs, or mediums found. Refactor is behavior-preserving: every happy/error path exercised produces identical output to main. Two pre-existing quirks re-observed (documented below as pre-existing). 1 note for maintainers.

In-scope bugs

None.

Pre-existing bugs (reproduce identically on main)

[medium] Commands exit 0 on error

• Reproducer:

  cd /tmp/empty-dir
  node dist/cli/index.mjs validate; echo "exit=$?"   # prints "No agentcore project found…" exit=0
  node dist/cli/index.mjs status;   echo "exit=$?"   # same
  node dist/cli/index.mjs status --json; echo "exit=$?"
  # inside a project, with malformed agentcore.json
  echo '{invalid json' > agentcore/agentcore.json
  node dist/cli/index.mjs validate;  echo "exit=$?"  # exit=0
  node dist/cli/index.mjs status --json; echo "exit=$?"  # exit=0

• Evidence it's pre-existing: Checked out origin/main (9afd3f0), rebuilt, reproduced identical output + exit=0 for every case. Not introduced by this PR.

[low] status --json prints human-readable text on error, not JSON

• Reproducer: With a malformed agentcore.json, status --json prints Error: Failed to parse JSON in config file… as plain text instead of a JSON error envelope.
• Evidence it's pre-existing: Same output on origin/main.

Notes

• invoke/logs/traces without a TTY print command help instead of an error. When running invoke --name X --prompt hello in a non-TTY shell, the CLI renders the subcommand help and exits 0 instead of reporting that an interactive terminal is required (or attempting non-interactive execution). Reproduces identically on main, so out of scope for this refactor; flagging for future UX work. The sole "interactive terminal required" message only surfaces for deploy.

What works ✓

• agentcore create --project-name bbtest --name myagent --defaults --skip-git --skip-install produces a valid project with correct agentcore.json.
• validate on a good project → Valid, exit=0.
• status / status --json on a good project → correct human + JSON output; resources array and deploymentState: local-only reported.
• Schema violations are surfaced with precise per-field errors:
  • {} → name: expected "string", version: expected "number".
  • runtimes[0].build: "BogusBuild" → expected "CodeZip" | "Container".
• Malformed JSON → Invalid JSON in agentcore.json: Expected property name… (position included).
• remove agent --name nonexistent -y → structured JSON {"success":false,"error":"Agent \"nonexistent\" not found."}.
• remove agent --name myagent -y → structured success JSON; subsequent status --json shows resources: [].
• remove all -y → {"success":true,"message":"All schemas reset to empty state"}.
• Build clean, --version prints 0.13.0, all CLI help rendered correctly.

Test coverage

Surface	Tested	Result
Build	yes	pass
CLI happy path (create/validate/status)	yes	pass
Error paths (missing project, malformed JSON, bad schema)	yes	pass (behavior identical to base)
Schema validation	yes	pass
Removal paths (remove agent, remove all, nonexistent)	yes	pass
Partition correctness	n/a	PR does not touch ARN/endpoint code

Refactor LGTM from a black-box behavioral standpoint — every tested surface produces identical stdout/stderr/exit code to main.