Skip to content

Show the updates[] wrapper in project-context write examples - #350

Open
VodouAI wants to merge 1 commit into
every-app:mainfrom
VodouAI:docs/project-context-update-shape
Open

VodouAI wants to merge 1 commit into
every-app:mainfrom
VodouAI:docs/project-context-update-shape

Conversation

@VodouAI

@VodouAI VodouAI commented Sep 20, 2026

Copy link
Copy Markdown

Nine skills document the research-log write as a bare patch op:

append a research log entry: `{ appendResearchLog: { summary: "..." } }`

Read as the tool's argument shape — which is how it reads without the surrounding call — that produces a silent data loss. update_project_context takes { projectId, updates }, and unknown top-level keys are stripped before the handler sees them. So an agent that sends appendResearchLog or addKeyPages at the top level alongside a valid updates[] gets Updated project context (1 change(s)) while that write is discarded.

Verified against a running instance:

  • top-level only, no updates[]Input validation error: updates: Invalid input: expected array, received undefined. Loud, fine.
  • valid updates[] plus a top-level addKeyPages → success, key page silently dropped.

The examples now show { updates: [{ appendResearchLog: { summary: "..." } }] }.

seo-project-setup is deliberately untouched: its op list already sits under update_project_context(projectId, updates), so the wrapper is implied there.

Found when an agent running seo-audit reported its research-log and key-page writes as successful and neither appeared.

Docs-only change — no behavior change. sync-plugin-skills re-run, idempotent, so the plugins/openseo/skills check stays green.

Nine skills documented the research-log write as a bare patch op,
`{ appendResearchLog: { summary } }`, which reads as the tool's argument
shape. Sent that way it is silently dropped: unknown top-level keys are
stripped, so a call carrying a valid updates[] alongside them reports
success while that write is discarded. Sent alone it fails validation
instead, which is at least loud.

seo-project-setup is left alone — its op list already sits under
`update_project_context(projectId, updates)`, so the wrapper is implied
there.
@VodouAI
VodouAI requested a review from bensenescu as a code owner September 20, 2026 05:52
@VodouAI

VodouAI commented Sep 20, 2026

Copy link
Copy Markdown
Author

The root cause here isn't really the skill wording — it's that unknown top-level keys are stripped silently. Every tool registers through registerOpenSeoTool, which normalizes inputs via objectSchema, so making input objects strict is a few lines in one place:

const normalized = objectSchema(tool.config.inputSchema);
inputSchema: normalized instanceof z.ZodObject ? normalized.strict() : normalized,

(Outputs would stay permissive, per the existing comment there.) That would turn this class of silent write-loss into a validation error across every tool, not just the ones documented here.

I didn't do it in this PR because it changes behavior for every client — anything currently sending a stray field starts getting a hard error instead of a quiet success, and you're better placed than I am to know whether that's true of any client in the wild. Happy to open it as a separate PR if you want it, either instead of or alongside this one.

@VodouAI
VodouAI force-pushed the docs/project-context-update-shape branch from 13e903a to ec3d8ce Compare September 20, 2026 06:26
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