Skip to content

Docs: Polishing get started, concepts, and overview.#205

Merged
nick-inkeep merged 18 commits intomainfrom
docs-concepts-page
Sep 14, 2025
Merged

Docs: Polishing get started, concepts, and overview.#205
nick-inkeep merged 18 commits intomainfrom
docs-concepts-page

Conversation

@nick-inkeep
Copy link
Copy Markdown
Collaborator

No description provided.

@vercel
Copy link
Copy Markdown

vercel Bot commented Sep 14, 2025

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

Project Deployment Preview Comments Updated (UTC)
agents-docs Ready Ready Preview Comment Sep 14, 2025 7:58pm
agents-manage-api Ready Ready Preview Comment Sep 14, 2025 7:58pm
agents-manage-ui Ready Ready Preview Comment Sep 14, 2025 7:58pm
agents-run-api Ready Ready Preview Comment Sep 14, 2025 7:58pm

@claude
Copy link
Copy Markdown
Contributor

claude Bot commented Sep 14, 2025

Claude finished @nick-inkeep's task —— View job


PR Review: Documentation Polish

I've reviewed the documentation improvements across the get started, concepts, overview, and API pages. This is a solid polish pass that addresses several important areas. Here's my detailed feedback:

Todo List:

  • Read and analyze all changed documentation files
  • Review content quality, clarity, and technical accuracy
  • Check consistency with existing patterns and navigation
  • Provide constructive feedback and recommendations

Positive Changes

Content Clarity & Accuracy:

  • Fixed grammatical issues ("there's a few ways""there are a few ways")
  • Corrected typos ("An Agent save information""An Agent can save information")
  • Removed duplicate words ("is is then made available""is then made available")
  • Improved structured outputs terminology consistency ("Structure Outputs""Structured Outputs")

User Experience Improvements:

  • Enhanced Quick Start with better pnpm setup instructions and clearer prerequisites
  • Improved API documentation by moving request context guidance to proper location (headers vs body)
  • Better positioning of development mode vs production API key usage

Content Structure:

  • Reorganized concepts page to have better logical flow (Agents/Tools → Graphs → Authentication → etc.)
  • Enhanced overview page description for better clarity on use cases

🔍 Areas for Further Consideration

Minor Content Issues:

  1. Quick Start duplication (quick-start.mdx:49-54):

    If used corepack for installing pnpm:

    This section appears redundant with the corepack command already shown in Step 1. Consider removing or clarifying when this separate step is needed.

  2. API documentation clarity (api.mdx:47-49):
    The note about request context in headers could be more prominent since this is a breaking change from including it in the JSON body.

Consistency & Patterns:

  1. Terminology alignment: Some inconsistency in referring to "TypeScript Agents SDK" vs "TypeScript Developer SDK" vs "Agents SDK". Consider standardizing throughout.

  2. Link structure: The overview page links to /typescript-sdk/agent-configuration but the concepts page references it as "Agent Settings" - ensure navigation consistency.

Technical Accuracy:

  1. Prerequisites positioning: The Node.js prerequisite tip was moved around in quick-start.mdx. Consider whether it should be at the very beginning before any installation steps.

📋 Overall Assessment

Strengths:

  • Excellent attention to grammatical details and typos
  • Good structural improvements to content flow
  • Appropriate technical corrections (especially API request context guidance)
  • Maintains consistency with existing documentation patterns

Impact: This polish pass significantly improves the user experience for developers getting started with the platform. The grammar fixes and structural improvements make the documentation more professional and easier to follow.

Recommendation:Approve with minor suggestions

The changes are solid and improve the documentation quality substantially. The areas I've highlighted are minor refinements that could be addressed in follow-up work rather than blocking this PR.


@nick-inkeep nick-inkeep merged commit 1e43c8c into main Sep 14, 2025
5 of 7 checks passed
@nick-inkeep nick-inkeep deleted the docs-concepts-page branch September 14, 2025 19:54
amikofalvy added a commit that referenced this pull request Mar 11, 2026
Fixes stack overflow with preserveOrder (CVE-2026-27942) in transitive
fast-xml-parser dependency.

Closes dependabot alert #205.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
amikofalvy added a commit that referenced this pull request Mar 11, 2026
Fixes stack overflow with preserveOrder (CVE-2026-27942) in transitive
fast-xml-parser dependency.

Closes dependabot alert #205.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
github-merge-queue Bot pushed a commit that referenced this pull request Mar 11, 2026
* fix(security): add dompurify override >=3.3.2

Fixes XSS bypass vulnerability (CVE-2026-0540) in transitive dompurify
dependency by adding pnpm override.

Closes dependabot alerts #210, #211.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(security): add fast-xml-parser override >=5.3.8

Fixes stack overflow with preserveOrder (CVE-2026-27942) in transitive
fast-xml-parser dependency.

Closes dependabot alert #205.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(security): add serialize-javascript override >=7.0.3

Fixes RCE vulnerability via RegExp.flags and Date.prototype.toISOString()
in transitive serialize-javascript dependency (build-time only).

Closes dependabot alert #203.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(security): add svgo override >=3.3.3

Fixes DoS via entity expansion in DOCTYPE (CVE-2026-29074) in transitive
svgo dependency (build-time only).

Closes dependabot alert #212.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(security): add minimatch override >=5.1.8 — ReDoS fix (#2642)

* fix(security): add minimatch override >=5.1.8

Fixes multiple ReDoS vulnerabilities (CVE-2026-26996, CVE-2026-27903,
CVE-2026-27904) in transitive [email protected] dependency.

Closes dependabot alerts #188, #199, #200.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(security): add lodash/lodash-es override >=4.17.23 — prototype pollution fix (#2643)

* fix(security): add lodash/lodash-es override >=4.17.23

Fixes prototype pollution in _.unset and _.omit (CVE-2025-13465)
in transitive lodash dependencies.

Closes dependabot alerts #120, #123.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(security): add express-rate-limit override >=8.2.2 (#2644)

Fixes IPv4-mapped IPv6 rate limit bypass (CVE-2026-30827) in transitive
express-rate-limit dependency.

Closes dependabot alert #213.

Co-authored-by: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

* fix(security): add security overrides to create-agents-template

Ensures self-hosted deployments using the template also get patched
transitive dependency versions.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(security): sync overrides between root and create-agents-template

Makes pnpm.overrides identical in both package.json files so the
monorepo and self-hosted template have the same security floor.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>
github-merge-queue Bot pushed a commit that referenced this pull request Apr 22, 2026
…) (#3176)

* wip: pre-push standardization scaffolding

* feat(ci): wire scoped pre-push runner into husky + update AGENTS.md

Completes the pre-push standardization started in the prior WIP commit.

- .husky/pre-push now runs `pnpm check:monorepo-traps` (whole-repo structural)
  then `pnpm check:pre-push` (scoped per-subtree). The scoped runner
  detects which subtrees changed versus `@{upstream}` and only runs fast
  CI-mirrored checks for them.
- AGENTS.md: new "Pre-push verification" and "Pre-commit verification"
  sections documenting the two-tier hook and the lint-staged routing.

* docs: add format cheatsheet entries + pre-push runbook section

* fix(ci): tighten check-pre-push error handling and docstring accuracy

Address PR #202 review feedback on scripts/check-pre-push.mjs:

- Remove migration-lineage and knip from header docstring. Neither is in
  PUBLIC_AGENTS_STRUCTURAL_CHECKS and both are intentionally excluded
  (migration-lineage needs clean DB state; knip is ~10-30s and noisy).
  Documented the omissions so future readers don't wonder.
- runScript: surface spawn errors (result.error) and signal termination
  (result.signal) with their own branches before falling through to the
  generic exit-status message. New contributors with missing pnpm now
  see a real diagnostic instead of 'exit null'.
- getChangedFiles: same treatment. Distinguishes spawn failure, signal,
  and non-zero exit so the fallback warning in main() carries useful
  context.
- resolveBaseRef: warn when git spawn fails outright. The silent
  origin/main fallback still stands for the expected case (no upstream
  configured), but corrupted repo / permission issues now surface.
- Remediation hint at the end: only suggest 'pnpm --dir X format' for
  subtrees whose format:check actually failed. Structural-check
  failures (route-handler-patterns, dal-boundary, etc.) aren't fixed
  by format, and the old blanket suggestion was misleading.

* fix(ci): declare lint-staged as root devDependency

Address PR #202 review feedback: lint-staged was listed only in
public/agents/package.json and not hoisted to root under pnpm's
isolated node_modules layout. 'pnpm lint-staged' at repo root then
failed with ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL, which meant the
pre-commit hook was a silent no-op.

Declaring lint-staged as a root devDependency at the same ^16.1.5
range as public/agents keeps the pre-commit hook functional from
the monorepo root. Only the root pnpm-lock.yaml changes; the
public/agents lockfile is untouched.

Verified: 'pnpm exec lint-staged --version' now resolves at root.

* feat(agents): Support more inline text attachment formats (#196)

* Support more inline text attachment formats

* Reduce allowlist test worker churn

* Update OpenAPI snapshot for text attachments

* Cleanup

* Add .cfg text document support

* Capture intermediate text in structured-output generation (#178)

* [US-001] Extend generationType literal union to include mixed_generation

Adds 'mixed_generation' to the AgentGenerateData.generationType union so
downstream consumers can record session events for agent turns that
produce both text and data parts. Includes a new test covering the
mixed_generation value.

Foundation for subsequent stories that compute and emit the new
discriminant from the post-stream resolution site.

* [US-002] Add write-queue serialization to IncrementalStreamParser

Serialize processTextChunk and processObjectDelta via an internal
promise-chain writeQueue so that concurrent fullStream and
partialOutputStream consumers cannot corrupt shared parser state
(collectedParts, buffer, pendingTextBuffer, hasStartedRole,
componentAccumulator, allStreamedContent, streamHelper).

External method signatures are unchanged. Method bodies are moved to
_doProcessTextChunk and _doProcessObjectDelta; the public methods chain
work onto writeQueue and catch rejections so a throwing write does not
break subsequent enqueued writes.

* [US-003] Consume fullStream + partialOutputStream concurrently for structured output

When hasStructuredOutput is true, handleStreamGeneration now runs
processStreamEvents against fullStream alongside the partialOutputStream
consumer via Promise.all. This ensures intermediate-step text-deltas
(e.g. 'Let me search...' emitted before a tool call) reach the parser
even when the final structured object fails to materialize, fixing the
blank-screen failure mode documented in SPEC.md.

Adds integration tests in __tests__/stream-handler.test.ts covering:
- both streams consumed concurrently when hasStructuredOutput is true
- fullStream text captured when partialOutputStream is empty
- falsy partial-output deltas filtered
- tool-call/tool-result/finish events forward to markToolResult
- error events surface via throw
- non-structured path does not iterate partialOutputStream
- tee-delivery ordering preserved with interleaved events

* [US-004] Extend post-stream fallback + mixed_generation discriminant + WARN log

* [US-006] Docs: document mixed_generation in agent_generate reference

Extend data-operations.mdx to cover the three-value generationType union
(text_generation, object_generation, mixed_generation) with a table and a
note on parts[] ordering for mixed responses. No changeset — agents-docs
is not published via the release-group flow.

* chore: add changeset for agents-api minor bump

Captures: dual-stream consumption, post-stream fallback, mixed_generation
generationType, and structured-output failure WARN log.

* chore: downgrade changeset from minor to patch

Ships as a bug fix — blank-screen failures in structured-output
agents. The mixed_generation generationType value is additive; no
breaking change. Patch is the correct semver classification.

* docs: describe mixed and text-fallback response shapes for dataComponents

data-components.mdx now documents the three response shapes a dataComponents
agent can return (object_generation, text_generation, mixed_generation) and
the text-fallback behavior when the model fails to produce a valid structured
object. status-updates.mdx event-type list updated to reflect that
agent_generate also covers mixed text plus structured output.

* fixup! local-review: address findings (pass 1)

* fixup! local-review: address findings (pass 2)

* chore: remove spec + research artifacts from branch

These are local ship workflow artifacts — the SPEC.md and research
report are worktree-only inputs, not part of the PR deliverable.

* style: auto-format with biome

* chore: address PR feedback on dual-stream + unknown part kind

Document the implicit AI SDK coupling between fullStream and
partialOutputStream that makes AbortController cancellation safe, and
warn when mapPartsToEventParts hits an unknown part kind instead of
silently producing an empty text part.

* fix: skip structured-output JSON text-deltas to prevent duplicate text

During structured-output generation, fullStream emits text-delta events
whose payload is the raw JSON encoding the schema. partialOutputStream
concurrently emits parsed object deltas for the same content. Feeding
both into the parser produced interleaved/duplicated text inside Text
component props (visible in the final dataComponents output).

Classify each step by its first non-whitespace text-delta character: if
'{' or '[', the step is emitting structured-output JSON — skip its
text-deltas and let partialOutputStream drive the parsed components.
Otherwise (free-form reasoning like "Let me search..." before a tool
call), forward text-deltas so intermediate text still reaches the
parser live. Reset classification on finish so multi-step flows are
judged per step.

* fix: parse fullStream JSON ourselves so multi-step structured output streams

In multi-step structured-output generation (e.g., agent emits text, calls
tool, then emits final structured JSON), partialOutputStream appears to
stop emitting after step 1 completes — its internal JSON accumulator
can't cleanly extend across the step boundary. Combined with the previous
skip-JSON-text-deltas guard, step 2's content never reached the parser
and the wire went dark after the tool call.

Replace the skip with active parsing: when a step's first text-delta
indicates JSON (starts with { or [), accumulate subsequent text-deltas
into a per-step buffer, run parsePartialJson on each update, and feed
the repaired cumulative object to parser.processObjectDelta — the same
entry point partialOutputStream uses. _doProcessObjectDelta's
length-based diffing and lastStreamedComponents tracking dedupe
naturally when both sources deliver the same snapshot, so the parallel
partialOutputStream consumer stays in place as a cooperating source.

The buffer resets on 'finish' so multi-step JSON doesn't concatenate
across steps (which would break parsePartialJson). Free-form reasoning
text (non-JSON) still flows through processTextChunk unchanged.

* fix: smoother structured-output text streaming + reset buffer per step

Three fixes layered on the multi-step structured-output streaming flow:

1. Reset the fullStream JSON buffer on 'finish-step', not just 'finish'.
   AI SDK v6 emits 'finish-step' between steps and 'finish' only at the
   very end. Without this, step 2's JSON text-deltas append onto step 1's
   closed JSON, parsePartialJson can't recover, and step 2 never streams.

2. Skip Text dataComponents in IncrementalStreamParser's
   "component-no-longer-in-accumulator" cleanup loop. When step 2 replaces
   the dataComponents array via deepMerge, step 1's Text id disappears
   from the current set and the loop flushes it through
   streamComponent → writeData('data-component', ...). But Text components
   were already streamed as text-delta wire events, so that flush produced
   a spurious data-component chunk duplicating the earlier text.

3. Drop the 50ms delay in IncrementalStreamParser's streamText calls.
   VercelDataStreamHelper.streamText sleeps delayMs between text-start
   and text-delta. The writeQueue serializes calls, so during the sleep
   more fullStream text-deltas accumulate in the JSON buffer and the next
   parsePartialJson produces a large diff. Result: 50ms becomes the
   effective chunk granularity (whole paragraphs per wire event). With
   delayMs=0, diffs flow at the rate parsePartialJson produces them,
   which is per-fullStream-text-delta granularity — much smoother.

* fix: insert \n\n between consecutive Text dataComponents

When a dataComponents array contains multiple Text components back-to-back
(with or without other components like citations interspersed), their
props.text gets streamed as text-delta wire events with no separator.
In Markdown rendering, adjacent paragraphs without a blank line between
them collapse into a single run-on block.

Emit '\n\n' before the first streamed chunk of any Text component whose
id differs from the previously streamed Text id. The separator fires only
on the initial streaming of a new Text id, so incremental updates to the
same Text id (typewriter streaming) still flow without breaks.

* refactor: extract streaming helpers and document the structured-output pipeline

Consolidates the fixes that enable token-level streaming of Anthropic
structured output, and extracts inline logic into well-named helpers so
the "what" reads as a sequence and the "why" lives in docblocks.

stream-handler.ts:
 - Docblocks on handleStreamGeneration (dual source rationale, abort
   wiring) and processStreamEvents (per-step classification, JSON buffer
   reset on finish-step).
 - Extract classifyStepMode, accumulateAndEmitJsonDelta,
   consumePartialOutputStream, normalizeStreamError.

IncrementalStreamParser.ts:
 - Class-level docblock tracing the full pipeline: jsonTool provider
   option, fullStream + partialOutputStream consumption, Text vs
   data-component wire mapping, paragraph separator, positional
   non-Text gating.
 - Module-level isTextComponent type guard — one place for the
   Text/non-Text routing decision.
 - Extract flushEvictedComponents, streamTextComponentDelta,
   emitTextToClient, rememberSnapshot from _doProcessObjectDelta. The
   method body now reads as two clearly-labelled steps (flush evicted,
   then walk current array) instead of two nested loops.

stream-helpers.ts:
 - Tighten the VercelDataStreamHelper.streamText comment to explain
   granularity (not pacing) is what makes rendering feel smooth.

generate.ts:
 - Tighten the providerOptions.anthropic.structuredOutputMode comment to
   cite the specific models affected (Sonnet 4.5, Opus 4.5, Opus 4.1)
   and the external context (vercel/ai#9195, the provider source file).

* style: auto-format with biome

* fix: make preludeEqualsOutput key-order independent

Comparing JSON.stringify(parsed) === JSON.stringify(output) is
order-dependent — two objects with identical content but different key
order would compare unequal and produce a duplicated prelude in the
rendered structured-output response. Canonicalise with a recursive
key-sort before stringifying so the comparison is purely structural.

* fix: enable jsonTool mode for Anthropic structured output streaming

Set providerOptions.anthropic.structuredOutputMode = 'jsonTool' on
streamText calls that use Output.object(). Without this, Claude Sonnet
4.5 / Opus 4.5 / Opus 4.1 buffer the final structured JSON server-side
and return it as a single giant text-delta event after 20+ seconds of
silence, because the default path routes through Anthropic's native
structured-outputs beta and Vercel AI SDK's createOutputTransformStream
gates publishing on parsePartialJson producing a new valid partial
(which it can't for deeply nested schemas until the tail).

jsonTool forces the synthetic-tool fallback path which streams tokens
as input_json_delta events and bypasses the transform gate entirely.

Known tradeoff, accepted: tool_choice: required (auto-set in jsonTool
mode) prefills the assistant turn, so Claude does NOT emit pre-tool-call
reasoning text. This is documented Anthropic API behaviour, not an SDK
bug. Existing data-operation events (tool_call, tool_result) still
surface tool activity to the UI, so users see the agent is working.

Verified neither @ai-sdk/anthropic upgrade (3.0.7 → 3.0.71) nor ai
upgrade (6.0.14 → 6.0.168) resolves the buffering — the transform-gate
has not been fixed upstream as of this commit. Community tracking:
vercel/ai#3422, #12427, #12298, #7220, #9351.

See the extensive comment in generate.ts for full rationale, the
alternatives considered, and references to the relevant source lines
and Anthropic docs.

---------



* Version Packages (agents) (#205)



* fix(ci): encode repository_dispatch client_payload as JSON object

v0.70.0 stranded because both the success and failure notify steps in
inkeep/agents' release.yml sent client_payload as a stringified JSON via
gh api --raw-field. The dispatches endpoint rejects that with HTTP 422
"is not an object", npm had already published, but the reverse-sync was
lost so no GitHub Release, no Vercel prod deploy, no tracking issue.

Switch both steps to build the request body with jq and pipe through
gh api --input -, which sends client_payload as a real JSON object.

Runbook gains a new entry documenting the 422 symptom, the gh api flag
encoding pitfall, and the manual -F 'client_payload[key]=val' recovery
command for any future stranding.

---------





GitOrigin-RevId: 6061f7757827aca72ac7dffd87a0fe07ea68b352

Co-authored-by: Varun Varahabhotla <[email protected]>
Co-authored-by: mike-inkeep <[email protected]>
Co-authored-by: tim-inkeep <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: inkeep-internal-ci[bot] <259778081+inkeep-internal-ci[bot]@users.noreply.github.com>
Zeeeepa pushed a commit to Zeeeepa/inkeep_agents that referenced this pull request Apr 23, 2026
GitOrigin-RevId: ca01cc752787e63908087c7c833c0e2ea315f9ac

Co-authored-by: inkeep-internal-ci[bot] <259778081+inkeep-internal-ci[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Zeeeepa pushed a commit to Zeeeepa/inkeep_agents that referenced this pull request Apr 23, 2026
* Follow-ups to inkeep#130: tsconfig pilot + skipped-test audit + stream-path any cleanup (inkeep#133)

* test: remove 2 obsolete skipped tests in push command

These two tests were empty-body `it.skip(...)` placeholders whose
comments explicitly documented why they were obsolete:

- `should override API URL from command line`: feature removed in
  favor of config-file-only approach (API URLs must now be in
  inkeep.config.ts, not CLI flags)
- `should handle missing configuration`: behavior tested by integration
  tests; unit-test path not feasible due to process.exit(1)

Part of a codebase-wide skipped-test audit. See
.audit-skipped-tests.md for the full audit.

* chore: add skipped-test audit summary

Temporary artifact documenting the 131-test skipped-test audit.
Full per-file table lives in /tmp/skipped-tests-audit.md.

- 131 skipped tests across 24 files (pattern: it.skip / describe.skip)
- Bucket A (unskip): 0 (verification loop blocked by Node version guard)
- Bucket B (delete): 2 applied in prior commit; 1 ~460-line block deferred
- Bucket C (needs owner): 128, clustered around 3 architectural migrations
- Bucket D: 0

This file may be removed before PR.

* chore(tsconfig): pilot strict baseline on 2 packages

Extend tsconfig.base.json in:
- public/agents/packages/agents-mcp (no source changes; already strict)
- public/agents/packages/agents-email (3 exactOptionalPropertyTypes fixes)

agents-email fixes:
- src/components/email-layout.tsx: conditional-spread optional
  'description' prop into EmailHeader
- src/index.ts: conditional-spread optional 'replyTo' in both
  sendInvitationEmail and sendPasswordResetEmail sendEmail calls

Evaluated but deferred to their own PRs (would exceed pilot scope):
- ai-sdk-provider: 15 errors, mostly LanguageModelV2 structural
  exactOptionalPropertyTypes mismatches that require interface-level
  changes
- create-agents: 30 errors across templates.ts/utils.ts from
  noUncheckedIndexedAccess + exactOptionalPropertyTypes

Builds on inkeep#130.

* fix(ci): wait for DBs to serve queries before Extended Validation tests

Extended Validation's doltgres + postgres service containers report healthy
via their docker health checks before the database/user objects are actually
queryable. Tests start, fail with 'database not found: appuser' /
DrizzleQueryError intermittently. See PR inkeep#200 and PR inkeep#205 failures.

Adds a hard barrier that polls each DB with SELECT 1 (30s max) after service
containers start but before tests run. Converts probabilistic 'health check is
close enough' into deterministic 'we proved the DB can serve queries.'

Applied to both:
- .github/workflows/public-agents-extended-validation.yml
- .github/composite-actions/public-agents-cypress-e2e/action.yml (replaces the
  existing DoltGres-only wait with a unified wait_for helper that also gates
  on the postgres runtime DB)

* chore(review): address non-signoz inline comments on inkeep#133

- .audit-skipped-tests.md: strip ephemeral `/tmp/skipped-tests-audit.md`
  reference; update branch name to the PR's actual branch
  (pullfrog review comment)

- agents-mcp/tsconfig.json: drop useUnknownInCatchVariables (already
  implied by strict: true inherited from tsconfig.base.json)
  (pullfrog + claude review comments; 1-click suggest)

Signoz-related review items dropped along with the signoz refactor.

* fix: drop engines.node to unblock inkeep-cloud-mcp Vercel deploys

The engines.node range added in inkeep#130 broke inkeep-cloud-mcp Vercel
builds on main (both preview and production). Mechanism: that project's
vercel.json does `cd ../.. && pnpm install` from repo root, which picks
up root engine-strict=true plus engines.node <23. Vercel's build env
runs Node 24, failing the constraint. The other three Vercel projects
install from their subdir and do not inherit this, so they kept
deploying successfully.

Deploy evidence on main:
- 4236e3d915 (pre-inkeep#130 merge, no engines): success
- 08d61f2938 (merge commit, engines added): failure (preview + prod)
- 1526cbcd90 (post-merge Dependabot bump): failure

Keeping .node-version: 22 (unrelated to Vercel) and engine-strict=true
in .npmrc (no-op without engines field, same state as pre-inkeep#130). The
postinstall check-node-version.mjs still enforces major-version match
for local dev.

GitOrigin-RevId: b72cd4cf7aa8144945fb05590c8bc804ef01be69

* chore(ci): align security-floor overrides and flip check:overrides to hard-fail (inkeep#204)

* chore(ci): align security-floor overrides and flip check:overrides to hard-fail

Aligned the four out-of-sync overrides between public/agents/package.json and root pnpm-workspace.yaml, using the higher floor in each direction to preserve security intent:

- @modelcontextprotocol/sdk: root pin 1.26.0 relaxed to >=1.26.0 (matches public/agents)
- fast-xml-parser: public/agents raised >=5.3.8 -> >=5.5.6
- lodash: public/agents raised >=4.17.23 -> >=4.18.0
- lodash-es: public/agents raised >=4.17.23 -> >=4.18.0

Regenerated both lockfiles that cover these overrides (root pnpm-lock.yaml and public/agents/pnpm-lock.yaml). No transitive version re-resolutions; the only changes are the override specifiers themselves.

Flipped check:overrides in scripts/check-monorepo-traps.mjs from soft-warn to hard-fail. Now matches the already-hard check:override-masks-bump, check:lockfiles, and check:workspace-membership. Any future drift between root and public/agents overrides is caught at PR time instead of by a cryptic Vercel install failure minutes after merge.

Also updated AGENTS.md and .github/CI_RUNBOOK.md to reflect the new hard-fail behavior.

Note: pre-commit hook skipped (pnpm lint-staged at root is a pre-existing local-setup issue unrelated to this PR). Files in this commit do not require biome formatting (lockfiles, yaml, package.json).

* chore(ci): align check:overrides error messages with doc language

The pullfrog review on PR inkeep#204 flagged that the checkOverridePlacement
remediation strings still pointed only at /package.json, while the
AGENTS.md and CI_RUNBOOK.md updates in the same PR now say overrides
can live in either /pnpm-workspace.yaml or /package.json at root.
Script logic already reads both locations via getRootOverrides(); this
is a wording-only fix so the error messages a developer sees match
what the docs tell them to do.

GitOrigin-RevId: 1633ad2aa24886fe2687dab6eb6ef9379786705a

* csv and rerun functionality (inkeep#200)

* csv and rerun

* style: auto-format with biome

* tests

* style: auto-format with biome

* TestS

* style: auto-format with biome

* library instead of manual parse

* lint

* snapshot

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
GitOrigin-RevId: fbfeb6d660e85d4269acf00efd35e885ad35365d

* fix(tsconfig): move tsconfig.base.json into public/agents/ for Copybara mirror compatibility (inkeep#209)

* fix(tsconfig): move tsconfig.base.json into public/agents/ for Copybara mirror compatibility

The root-level tsconfig.base.json added in inkeep#130 lives outside public/agents/**,
so Copybara's stripPrefix: "public/agents" does not mirror it to inkeep/agents.
After the sync, per-package tsconfigs referenced ../../../../tsconfig.base.json
which resolves above the repo root on inkeep/agents, causing agents-email#build
to fail with TS5083.

PR inkeep#130 originally documented a 2-level extends path in the base file's own
comment ("Extend with { \"extends\": \"../../tsconfig.base.json\" }"), which
is only correct if the base sits at public/agents/tsconfig.base.json. The file
was placed at the wrong directory.

This moves the file under public/agents/ and updates the two consumers
(agents-email, agents-mcp) to use the intended 2-level path. Path resolves
correctly in both repos now.

* docs(public-agents): document tsconfig.base.json convention for new packages

* docs(tsconfig): drop em dashes in new section to match repo writing style

GitOrigin-RevId: 89ee740d87232ae68cb8195558c1fb1af7b2a462

* chore(ci): remove redundant public-repo ci.yml and cypress.yml (inkeep#211)

* chore(ci): remove redundant public-repo ci.yml and cypress.yml

All lint/typecheck/test/build/Cypress validation already runs on agents-private
pre-merge via Core Validation, Extended Validation, and public-agents-cypress.
The public-side duplicates re-ran the same checks on Copybara sync PRs (code
already exhaustively validated), costing ~30m (ci) + ~15m (cypress) per sync
on ubuntu-32gb runners.

External PRs to inkeep/agents bridge back to agents-private via
monorepo-pr-bridge.yml for canonical validation, so no coverage is lost.

- Delete public/agents/.github/workflows/ci.yml
- Delete public/agents/.github/workflows/cypress.yml
- Delete orphaned composite actions (changeset-check, cypress-e2e)
- Update CI.md workflow map, parity table, branch protection
- Update CI_ARCHITECTURE.md install composite-action reference
- Update cypress-e2e composite README (agents-private only caller)
- Update internal-surface-areas skill to point at upstream workflows

Coordinated with CTO: 'ci' and 'Cypress E2E Tests' required checks removed
from inkeep/agents branch protection.

* chore(ci): also remove redundant public-repo ci-maintenance.yml

With ci.yml and cypress.yml gone, the public repo has no substantive CI
for the weekly CI Maintenance Claude job to analyze. The equivalent
analysis runs on agents-private via public-agents-ci-maintenance.yml,
which sees the real CI surface.

- Delete public/agents/.github/workflows/ci-maintenance.yml
- Update CI.md workflow map + parity table
- Update internal-surface-areas skill

* chore(ci): clean up stale ci.yml references flagged by PR review

- Update two stale comments in public-agents-extended-validation.yml
  that referenced the now-deleted public/agents ci.yml
- Delete obsolete public/agents/specs/changeset-only-skip-ci/SPEC.md;
  the changeset-skip feature it documented lived inside ci.yml and the
  changeset-check composite action, both removed in this PR

GitOrigin-RevId: 63d06e27c8a374e100270f3118f64cd2170e0d6a

* fix(ci): close remaining silent-failure gaps in release cascade (inkeep#212)

* fix(ci): close remaining silent-failure gaps in release cascade

Five hardening fixes across the release pipeline. None of these change
pipeline shape (CTO-asked streamlining was evaluated separately and
deferred — it saves ~1 min E2E but closes zero real failure modes).

Each change addresses a distinct way the cascade can silently strand:

1. release-handler.yml: widen notify-handler-failure to catch failure-job
   failures too. Previously only caught success-job failures; if the
   failure-dispatch handler's own gh issue create 4xx'd (label API
   hiccup), the npm publish failure went completely untracked. Needs
   chain now covers [success, failure] and the issue body adapts to
   which job failed.

2. public-mirror-sync.yml: 3-attempt retry on gh pr list before exit 0
   in the copybara/sync reconcile step. Previously a single transient
   API flake skipped reconciliation entirely, letting Copybara run over
   a potentially-stuck sync branch — exactly the local/origin history
   conflict class that issue inkeep#188 fixed via reconcile. Exit 0 on
   exhaust is preserved (deleting a live PR's branch on persistent
   outage is worse than letting Copybara try its own fast-fail).

3. public/agents/.github/workflows/release.yml: add npm view
   ground-truth check after the grep-based "packages published
   successfully" marker. The log-phrase check catches phrase drift
   but not partial-publish (package N fails after N-1 succeed leaves
   the marker in the log). Now iterates every @inkeep/ workspace
   package and verifies each exists on npm at VERSION; any miss
   fails the step with a specific error so the failure notifier
   fires instead of silently reporting green.

4. scripts/check-monorepo-traps.mjs: add
   public/agents/agents-cookbook/evals/langfuse-dataset-example to
   DUAL_LOCKFILE_ROOTS. The directory is carved out as a
   STANDALONE_WORKSPACE_BOUNDARIES entry (users clone the example
   standalone) but its lockfile wasn't being checked for freshness.
   A dep change there could have shipped a broken install. The two
   sets now stay in sync by construction (noted in comment).

5. New release-version-drift-watchdog.yml: scheduled 3-way version
   check every 30 min across agents-core/package.json on main,
   @inkeep/agents-core latest on npm, and latest GH Release tag.
   Opens a tracking issue if drift persists past a 60-min grace
   window (bounds worst-case silent-stranding detection latency to
   30 min regardless of which workflow failed silently). Auto-closes
   the issue when drift resolves.

Audit finding inkeep#1 from yesterday's staff-engineer audit was retracted
(Doltgres branch-sync dead gate) — git blame + runtime evidence from
v0.69.0 and v0.70.0 deploys confirm the gate is working as designed
(migrate-dolt.ts emits the migrations_applied output correctly).

* fix(ci): address PR inkeep#212 review + bump watchdog cadence

Response to pullfrog + claude review findings on inkeep#212.

Watchdog timing bumps (per ask):
- Cron: every 30 min -> every hour on the top of the hour
- Grace window: 60 min -> 90 min
Normal release cascade is 20-30 min, worst legitimate tail (npm
propagation lag + Vercel queue) is ~60-90 min. 90 min grace absorbs
that without meaningfully raising detection latency (worst-case is
still grace + cron = ~2.5 hours vs. the unbounded default).

Watchdog correctness:
- gh pr list now uses `sort:updated-desc`. Default search relevance
  ordering doesn't guarantee --limit 1 returns the most recent merge
  when all Version PR titles are near-identical.
- Version PR lookup distinguishes real API failure from "no PR found".
  Previously both emptied LAST_VERSION_PR_MERGED_AT, silently bypassing
  the grace window on a transient API hiccup and producing false-
  positive drift alerts during legitimate in-flight releases. On
  failure we now warn explicitly and let drift be treated as real —
  intentional: a genuine API outage should alert, not suppress.
- Tracking issue lookup now uses --label release-drift-watchdog
  instead of `in:title "Release version drift detected"`. Title-
  substring search could match or close an unrelated human-authored
  issue whose title shared the phrase. The new label is this
  workflow's private marker, created alongside the existing `release`
  label in the defensive label-ensure loop. Issues opened by the
  watchdog get both labels.
- Auto-close step is now non-fatal. Drift is already resolved by the
  time this step runs, so a failed `gh issue comment` or
  `gh issue close` on a cleanup path should emit a warning instead of
  turning the run red. Next scheduled tick retries.

release.yml (inkeep/agents mirror) — npm propagation retry:
- Per-package `npm view` now retries up to 4 times with escalating
  backoff (2s, 4s, 8s, 16s — 30s cumulative wait per package) before
  declaring a package genuinely missing. The registry write path is
  synchronous but the CDN read path can lag by seconds. Previous
  single-shot check could false-positive during normal propagation,
  firing the failure notifier unnecessarily.
- Success path still exits on attempt 1 with a single npm view call
  — retry only engages when a package is not yet visible.
- Updated error message to note propagation is already ruled out.

Documentation catch-up:
- AGENTS.md: lockfile count 3 -> 4 with the langfuse-dataset-example
  entry that PR inkeep#212 adds. Explains the distinction between the two
  primary install-driving lockfiles (root + public/agents) and the
  two standalone lockfiles (starter kit + eval example) that ship
  with their own workspace so users can install subdirectories
  directly.
- CI.md: new workflow row under "Release and publishing" for the
  watchdog. Trigger now says "schedule (hourly)" to match the cron
  bump.
- package.json: `install:all` script now includes the langfuse
  lockfile directory. Previously check:lockfiles validated four
  entries but the regen shorthand only covered three, which would
  have left the fourth drifting silently the first time its package.json
  got updated.

* fix(ci): swap chat-to-edit-validation to resilient install composite

The failure on PR inkeep#212 (chat-to-edit / lint) was Corepack lazy-downloading
pnpm from the npm registry on first pnpm invocation (`pnpm store path
--silent` in this workflow). The undici SocketError during that download
left STORE_PATH unset, which actions/cache rejected with "Input required
and not supplied: path" — cascading skip of install/build/lint with no
actionable signal.

Swap the inlined setup-node + corepack + manual `pnpm store path` +
actions/cache + `pnpm install` chain for a single `uses:
./.github/composite-actions/install`. The composite downloads pnpm
directly from GitHub releases via pnpm/action-setup (different CDN
than corepack's npm registry fetch, empirically stable). 7 publish/
deploy workflows already use this pattern without hitting the flake.

Deferring the same migration on the other 9 inlined-pattern workflows
(agents-ui / copilot-app / copilot-chrome-extension / inkeep-cloud-mcp /
auto-format / private-pr-validation / public-agents-core-validation /
public-agents-extended-validation / public-agents-cypress) to a follow-
up. Several have custom steps (Playwright cache, Turbo cache, pre-install
biome, non-frozen-lockfile for auto-format) that need per-file review —
blind-swap would risk breaking a required check.

GitOrigin-RevId: 8c2e367004865bfe09daa1867296826c8b6c9db0

---------

Co-authored-by: Varun Varahabhotla <[email protected]>
Co-authored-by: shagun-singh-inkeep <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
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