Upgrade/mastra v1

[tnkshuuhei]

• Feat/mastra skills #190

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
muse	Ready	Preview, Comment	Feb 25, 2026 9:14am

[claude]

PR Review: Upgrade/mastra v1

This PR upgrades the Mastra AI framework from v0.x to v1.x, adapts to the updated Hypercerts API schema, and removes the git submodule approach in favor of the @beaconlabs-io/evidence npm package. Overall this is a solid, well-scoped migration. The changes are largely mechanical and appropriate for the API breaking changes. A few things are worth addressing before merge.

---

Code Quality & Correctness

mastra/tools/logic-model-tool.ts – API signature change

// Before
execute: async ({ context }) => {
  const { intervention, ... } = context;

// After
execute: async (inputData) => {
  const { intervention, ... } = inputData;

This looks correct for the Mastra v1 execute API, but please confirm the full inputData shape matches what was previously destructured from context. If Mastra v1 wraps input differently (e.g. inputData.context vs the raw shape), this could silently produce undefined values passed to generateLogicModel.

mastra/tools/get-all-evidence-tool.ts

execute: async (_inputData) => {

Renaming the unused parameter to _inputData is fine. One minor observation: the _ prefix convention is good, but if the type system allows it, declaring execute: async () =>... (no param) would be cleaner – unless Mastra v1 requires the parameter.

mastra/index.ts – telemetry removed

// Removed:
telemetry: {
  serviceName: "Muse",
  enabled: false,
},

Was this removed because the Mastra v1 API changed, or intentionally dropped? If it was disabled before (enabled: false), this is a no-op change in behavior, but it's worth documenting the reason in the PR description to make it clear this was intentional and not accidental.

mastra/agents/*.ts – id field added

Adding explicit id fields ("evidence-search-agent", "logic-model-agent") is good practice for Mastra v1 — agent identity is important for tracing and routing. No issues here.

---

Potential Bugs / Issues

app/actions/canvas/runWorkflow.ts – createRun vs createRunAsync

// Before
const run = await workflow.createRunAsync();

// After
const run = await workflow.createRun();

createRun appears synchronous here — make sure this isn't returning a Promise that should be awaited. If Mastra v1 changed this to synchronous, the await is harmless (awaiting a non-Promise just returns the value), but it should be verified so the intent is clear.

configs/hypercerts.tsx – API version downgrade to v1

// Before
const prodGraphql = "https://api.hypercerts.org/v2/graphql";

// After
const prodGraphql = "https://api.hypercerts.org/v1/graphql";

This is a downgrade from v2 → v1. The GraphQL schema changes in getAllHypercerts.ts (HypercertWhereInput → HypercertsWhereArgs, sortBy → sort, arrayOverlaps → overlaps) are consistent with this. However, v1 may have fewer features or different data availability than v2. Please confirm this is intentional and that there's no data or feature regression from this downgrade.

app/actions/hypercerts/getAllHypercerts.ts – burned filter removed

// Removed from createFilter:
where.burned = { eq: burned };

The burned filter no longer exists in the v1 schema, so this removal makes sense. However, the app/hypercerts/page.tsx previously passed burned: false explicitly to exclude burned hypercerts from the list. Without this filter, burned hypercerts will now appear in the listing. Confirm whether the v1 API excludes burned certs by default, or if this could lead to stale/invalid hypercerts appearing in the UI.

---

Temporarily Disabled Functionality

Two pieces of UI have been disabled with placeholder comments:

app/canvas/mint-hypercert/page.tsx

// disabled={!isConnected || !form.formState.isValid}
disabled={true}

components/canvas/CanvasToolbar.tsx

<DropdownMenuItem disabled={true} onClick={saveLogicModel} ...>

This is reasonable for a draft PR mid-migration, but the commented-out original condition should be either restored or removed before merge. Leaving dead code as comments creates confusion about intended behavior and will likely be forgotten. Consider a TODO comment with a ticket reference, or restore the condition if it's compatible with the new Hypercerts SDK.

---

Dependency Changes

The lockfile changes are large but consistent with the major version bumps:

• @mastra/core: ^0.24.0 → ^1.4.0
• @mastra/rag: ^1.3.4 → ^2.1.0
• mastra: ^0.18.0 → ^1.0.0

The removal of packages like @grpc/grpc-js, @grpc/proto-loader, @apidevtools/json-schema-ref-parser, and multiple @ai-sdk/*-v5 aliases from the lockfile suggests Mastra v1 has significantly slimmed its dependency tree. This is a positive change.

---

Documentation

The documentation updates are consistent and accurate:

• Removing PROJECT_ROOT references (good — the workaround is no longer needed)
• Updating file locations to reflect the npm package approach
• Removing submodule instructions from README

One suggestion: the docs/evidence-workflow.md still references lib/evidence.ts for evidence parsing. If getAllEvidenceMeta is now imported directly from @beaconlabs-io/evidence/content (per the changes to lib/evidence-search-batch.ts and mastra/tools/get-all-evidence-tool.ts), verify whether lib/evidence.ts is still the right reference or if it has been superseded.

---

Summary

Area	Status
Mastra v1 API migration	✅ Looks correct
Hypercerts API v1 query schema	✅ Consistent
Evidence npm package migration	✅ Clean
burned filter removal	⚠️ Verify no regression
API version downgrade v2→v1	⚠️ Confirm intentional
Disabled mint/save UI	⚠️ Track and restore before shipping
Telemetry config removal	⚠️ Document intent
Dependency cleanup	✅ Positive

Since this is a draft PR, the disabled UI and pending verifications are expected. Address the burned filter question and the API version intentionality before moving to review-ready state.

---

Reviewed by Claude (claude-sonnet-4-5-20250929)

[claude]

PR Review: Upgrade/mastra v1

This is a solid upgrade from Mastra v0.24/0.18 to v1.4/2.1/1.0. The Workspace Skills API refactor is a meaningful architectural improvement — externalising domain knowledge from inline agent instructions into dedicated skill files improves maintainability and reusability. Below are my findings.

---

What's working well

• Agent IDs added — assigning explicit id fields (evidence-search-agent, etc.) is the right move for v1 and important for workflow tracing.
• Robust tool result extraction — switching from toolResults[0] to .find(tr => tr.payload?.toolName === 'logicModelTool') is more resilient to multi-step agent responses.
• maxSteps: 5 on agent calls — necessary to accommodate the skill-activate → tool-call sequence; good that this was added in both the workflow step and the batch search.
• Error logging improvements — the new log output of allToolNames before the error makes debugging much easier when logicModelTool is not called.
• Import simplification — moving getAllEvidenceMeta from @/lib/evidence to @beaconlabs-io/evidence/content directly removes an unnecessary indirection layer.

---

Concerns

1. Relative basePath + absolute-looking skills path (potential runtime failure)

// mastra/index.ts
const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: ".",       // relative to cwd at runtime
  }),
  skills: ["/mastra/skills"],  // starts with "/" — absolute?
});

The skills path "/mastra/skills" looks like it could be treated as an absolute filesystem path rather than relative to basePath: ".". If Mastra's LocalFilesystem joins basePath with the skills path, leading slash behaviour needs clarification in the Mastra v1 docs/source. If it's interpreted as absolute it will fail everywhere except a system where /mastra/skills happens to exist.

Also, basePath: "." retains the same CWD-dependent path resolution that PROJECT_ROOT was introduced to fix. Is there a Mastra v1 test or doc confirming the bundled output resolves "." back to the project root? If not, this may silently break in the .mastra/output execution context.

2. Removed retry logic with no replacement guard

The generateWithRetry helper has been removed entirely. When format validation fails (tool input errors), the call now throws immediately without any recovery path. The skills system reduces the probability of format errors by externalising instructions, but doesn't eliminate them. Consider whether a lightweight catch-and-log at the call site (or simply keeping a single retry pass) would improve resilience in production.

3. Pervasive any casts in the workflow

// mastra/workflows/logic-model-with-evidence.ts
const logicModelResult = result.toolResults.find(
  (tr: any) => tr.payload?.toolName === "logicModelTool",
) as any;

The removal of the typed LogicModelToolResult cast in favour of blanket any means TypeScript can no longer catch field renames or schema drift here. If Mastra v1 exports proper types for tool result payloads, using them would be preferable. At minimum, a narrow inline type for the expected shape would prevent silent runtime failures.

4. Skill activation is implicit with no fallback

Agent instructions now read:

Use the "evidence-matching" skill for the chain-of-thought evaluation framework…

but there's nothing in the agent config or workflow that enforces skill activation before the tool call. If the agent skips activation (e.g., hit a step limit earlier in the conversation), it will proceed with only the slim inline instructions. The behaviour in that case is silent degradation — the model just has less context — which is hard to detect. Consider adding a check or a warning log if the skill-activate tool was not called, similar to how the missing logicModelTool call is now detected.

5. Removed telemetry config

-  telemetry: {
-    serviceName: "Muse",
-    enabled: false,
-  },

Removing the block entirely means there's no commented-out reference point for future re-enabling. With Mastra v1 being a major upgrade, this is a good moment to either wire up real telemetry or keep the block as documentation. Silently omitting it makes it easy to forget the capability exists.

6. _inputData unused parameter in get-all-evidence-tool

// mastra/tools/get-all-evidence-tool.ts
execute: async (_inputData) => {

If _inputData is genuinely unused (no input schema fields), this is fine, but it reads oddly alongside the inputSchema definition. A brief comment (e.g., // Mastra v1 requires an execute signature with the input parameter) would clarify intent.

---

Minor / nits

• lib/evidence-search-batch.ts: the agent call gained { maxSteps: 5 } — consider a code comment explaining why 5 steps are needed (skill activation + tool call = 2, leaving headroom). This will help future maintainers not accidentally lower it.
• Skill SKILL.md tags field: the value is a comma-separated string ("evidence, matching, scoring…"). Check Mastra's spec — some skill frontmatter parsers expect a YAML array (tags: [evidence, matching]). Using the wrong format could cause skill metadata to not parse correctly.
• basePath: "." vs basePath: process.cwd(): if the intent is to always resolve from the project root, using process.cwd() explicitly makes the intention clear (even if it has the same CWD caveat as a bare dot).

---

Summary

The skills architecture is the right long-term direction and the agent instruction slimming makes the codebase significantly easier to maintain. The main risks worth addressing before merge are the path resolution question for the Workspace (basePath + skills path) and the loss of type safety from removing LogicModelToolResult. Everything else is lower-priority polish.