Repository navigation
S23: spec subpath export - #871
Merged
Merged
Conversation
…ow spans Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Every guardrail check (input, runInParallel input, output, tool) emits a `guardrail <name>` span: input/output checks nest under the run's invoke_agent span, tool checks under that call's execute_tool span. The span carries only ids and the outcome (lousho.guardrail.name, .kind, .outcome, .parallel for parallel input checks, gen_ai.tool.name for tool checks) - never the checked text or the trip reason. With no exporter or no parent span the check runs directly, as before. Spec-built agents stamp lousho.node.id = guard:<id>: NodeIdIndex gains guardrailByName (entry id -> guard:<id>; S11 names each compiled guardrail by its spec entry id) and the exporter maps 'guardrail ' spans through it. Unknown names (code-built, inherited) stamp nothing. Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Add an `approval` flow node (ApprovalStepNode in RuntimeStep) so a human
gate can be its own step: the context's approve callback decides a
flow_approval request carrying { message, stepId }, or a durable run
pauses with status 'awaiting-approval' until FlowExecutor.resume()
brings the decision - exactly as a toolCall that needs approval does.
- flowToolGate: requireApproval renamed to exported requireFlowApproval,
taking { toolName, toolCallId, args, subject }; toolCall error
messages unchanged via subject "Tool '<name>'".
- FlowExecutor: approval handler + executeApprovalStep; outputVariable
receives true once approved; refusal fails LOUSHO_FLOW_TOOL_DENIED.
- docs/flows.md: approval node row + Approval steps section.
- Regenerated api/*.api.md and llms-full.txt.
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…-s23-spec-subpath # Conflicts: # docs/observability.md # llms-full.txt # src/spec/v2/nodeIdExporter.test.ts # src/spec/v2/nodeIdExporter.ts
Add a browser-safe lousho/spec subpath that re-exports the spec v1/v2 schemas, their spec types and the pure helpers Studio needs (catalogs, upgradeSpec, agentSpecV2JsonSchema, specToCode, specNodeIds + nodeIdExporter, flowProblems + flowSpecSchema, triggerSpecSchema + listTriggerTypes) with no node:* imports anywhere in its graph. listBuiltinTools is not exported: its catalog builds the real tool factories, which pull node:net via web_fetch — it stays on the root. Two leaf extractions keep the provider/executor stack out of the browser bundle: approvalTtl.ts (approvalTtlMs/ttlMs helpers, re-exported by execution/permissions.ts) and guardrailLists.ts (PII_TYPES and MODERATION_CATEGORIES, consumed by spec/guardrailOptions.ts). Studio's importExport.ts drops its deep ../../../../src/spec/schema import for lousho/spec. Also: api/spec.api.md, typedoc/tsconfig/ fallow wiring, a packed-size budget bump in pack-smoke (+~33 KiB for dist/spec/), JSDoc on the spec section types the entry re-exports (ratchet baseline 1735 -> 1724), and the leftover merge-conflict markers in nodeIdExporter.test.ts resolved keeping both tests. Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
# Conflicts: # api/executor.api.md # api/flows.api.md # api/index.api.md # api/kv.api.md # api/sqlite.api.md # api/types.api.md # api/utils.api.md # api/worker.api.md # scripts/pack-smoke.ts # src/spec/v2/flow.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
New
lousho/specsubpath — a browser-safe entry that re-exports the merged spec surface with nonode:imports anywhere in its graph:agentSpecSchema+AgentSpec; v2agentSpecV2Schema,parseAgentSpecV2,AgentSpecV2and every section spec type (ToolRef,SkillRef,MemorySpec,GuardrailSpec,HandoffSpec,HookSpec,PermissionRuleSpec,McpServerSpecV2,TriggerSpec,OutputSpecV2,SubagentSpec,InlineAgentSpec, ...)upgradeSpec,secretRefSchema/isSecretRef/SecretRef,toolRefSchema/TOOL_REF_KINDS,memorySpecSchema,skillRefSchema,triggerSpecSchema,outputSpecSchemahelpers (jsonSchemaToStandardSchema),agentSpecV2JsonSchema/SPEC_FIELD_DESCRIPTIONS,specToCode,listModels,listGuardrails,listTriggerTypesspecNodeIds,SpecNodeIds,nodeIdExporter,nodeIdIndexOf,isNodeIdExporter,NodeIdIndexflowSpecSchema,flowProblems,FlowProblem,AgentFlowlistBuiltinToolsis not exported per the ticket's drop rule: its catalog builds the real tool factories, which pullnode:netviaweb_fetch— it stays on the package root (noted in the entry's JSDoc).Two leaf extractions keep the provider/executor stack out of the bundle (previously
agentSpecV2Schemaalone reached them):src/execution/approvalTtl.ts—MAX_APPROVAL_TTL_MS/isApprovalTtl/APPROVAL_TTL_RULE, re-exported byexecution/permissions.ts(no API change)src/execution/guardrailLists.ts—PII_TYPES/MODERATION_CATEGORIES, consumed byspec/guardrailOptions.ts(internal-only; public surface unchanged)Wiring:
package.jsonexports/typesVersions,tsupspec/indexentry,typedoc.jsonentry point, roottsconfig.jsonlousho/specpath,.fallowrc.jsonentry (type-only re-exports),api/spec.api.md, mechanical dist→src overrides inexamples/imports.test.tsandscripts/verify-docs-snippets.ts(src/spec/index.ts is already the v1 barrel).Studio:
importExport.tsdrops its deep../../../../src/spec/schemaimport forlousho/spec— the only deepsrc/specvalue import inapps/agent-forge.Extras: merge-conflict markers left in
nodeIdExporter.test.tsfrom the S20b/S20c merges are resolved keeping both tests;dist/spec/*(+~33 KiB) pushed the tarball over the packed budget —pack-smoke.tscomment notes it and the cap moved 5 → 5.5 MiB; JSDoc on the spec section types lowered the typedoc ratchet baseline 1735 → 1724. The diff also contains the two merge commits pullingfb-s20b-guardrail-spans/fb-s20c-handoff-spansinto this branch (S20a–c node-id exporter + guardrail/marker spans) — expected extras of the stacked-PR layout.Tested
npx tsc --noEmit,npm run typecheck:tests,npm run lint— cleannpm run test:coverage -- --minWorkers=1 --maxWorkers=4— 490 files / 7283 tests pass, thresholds metsrc/spec/v2/index.test.ts— esbuildplatform: 'browser'bundle has nonode:import in its metafile graph and zero resolve errors; export key list assertednpm run api:check— all 21 reports up to date (api/spec.api.mdnew; others only lose// (undocumented)markers via the new JSDoc)npm run fallow— clean (0 dead exports/files)npm run docs:ratchet— 1724 < 1735, baseline lowered and committednpm run docs:llms:check,npm run size-check,npm run docs:verify-snippets -- --source-only— pass (stage A resolveslousho/spec)npm run build,npm run build --workspace apps/agent-forge,npm run typecheck --workspace apps/agent-forge,npm test --workspace apps/agent-forge -- --run(968 tests) — passnpm run pack-smoke— all checks pass: 982 entries, ESM and CJS both load all 21 subpaths incl.lousho/spec, strict-libs clean under zod 3 and zod 4Acceptance criteria
import { agentSpecV2Schema, upgradeSpec, specToCode, listTriggerTypes } from 'lousho/spec'works from ESM and CJS (pack-smoke imports every subpath both ways — the package's real name islousho, so the subpath islousho/spec)node:in the graph)api/spec.api.mdexists andnpm run api:checkpassesnpm run build --workspace apps/agent-forge) with no deepsrc/specvalue import leftnpm run docs:verify-snippets -- --source-onlypasses (stage A now resolves/spec)Generated with Devin