feat(openrouter-typescript-sdk): add manual tools, approval flows, and streaming docs#7
Open
mattapperson wants to merge 10 commits intomainfrom
Open
feat(openrouter-typescript-sdk): add manual tools, approval flows, and streaming docs#7mattapperson wants to merge 10 commits intomainfrom
mattapperson wants to merge 10 commits intomainfrom
Conversation
… section Document the critical behavior that when a manual tool (execute: false) is called during a multi-turn callModel invocation, the SDK stops the loop and returns with the model's tool-call response in finalResponse.output. Includes patterns for approval flows, streaming detection, resuming after approval, and mixing manual with automatic tools.
…lows The previous commit incorrectly conflated manual tools with approval flows. These are two distinct SDK features: - Manual tools (execute: false): loop exits, developer handles execution externally, passes results back via function_call_output on next call - Approval flows (requireApproval): built-in SDK feature where the loop pauses to 'awaiting_approval' status, developer provides approveToolCalls or rejectToolCalls on next call, state persisted via StateAccessor Rewrites the Manual Tools subsection, replaces the combined section with separate "Manual Tool Execution" and "Approval Flows" sections covering the full lifecycle of each.
… emission Add section explaining that function_call items in getItemsStream() are emitted cumulatively — the same tool call is yielded multiple times with progressively longer arguments. JSON.parse always succeeds because callModel heals partial JSON in arguments and structured results.
…mulative getNewMessagesStream() yields cumulative message snapshots, not deltas. Each message event contains the full text up to that point. Updated the section heading, description, and example to make this clear and warn against appending content across events.
Merge the getNewMessagesStream() and getItemsStream() sections under a shared "Cumulative Streams" heading. Both yield cumulative snapshots (not deltas) — the same item is emitted multiple times as it grows. Consistent framing, shared warning about replacing vs appending, and contrast with delta-based streams.
…rom PR #16475 Update cumulative streams docs to match the implementation in OpenRouterTeam/openrouter-web#16475: - isComplete flag on all items from getItemsStream() and getNewMessagesStream() (false while streaming, true on final emission) - parsedArguments on function_call items in getItemsStream() — best-effort parsed object from healed JSON via healJson() utility - WithCompletion<T> type wrapper - StreamingFunctionCallItem type with parsedArguments field - Updated type signatures, examples, and response methods table
Rename streaming function_call fields so the healed parsed object is the primary 'arguments' field and the raw accumulated JSON string is 'rawArguments'. This makes the common case (accessing parsed args) the default, with the raw string available when needed.
…-the-loop only Manual tools (execute: false) are specifically for flows where a human produces the tool call result. Updated descriptions, examples, and contrast with approval flows throughout. Replaced programmatic examples (db queries, deploys) with human-in-the-loop examples (asking the user questions, collecting preferences).
…flows Remove misleading cross-references suggesting approval flows as an alternative to manual tools. These are separate, independent mechanisms.
…ences/ Move detailed authentication (OAuth, key management) and type/event shape definitions to references/ files per progressive disclosure principle. SKILL.md retains core procedural knowledge and behavioral docs (cumulative streams, manual tools, approval flows). Reduces SKILL.md from 1575 to 1045 lines. New files: - references/authentication.md — OAuth flow, key management, security - references/types-and-events.md — message shapes, event interfaces, stream types
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
1 participant
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.
Summary
execute: false) — specifically for human-in-the-loop flows where a person produces the tool call resultrequireApproval,state,approveToolCalls/rejectToolCalls) as a separate mechanism from manual toolsgetItemsStream()andgetNewMessagesStream()as cumulative snapshot streams (not deltas), withisCompleteflag and healedarguments/rawArgumentsfields per OpenRouterTeam/openrouter-web#16475isCompleteflag: All items from both cumulative streams carryisComplete: boolean—falsewhile streaming,trueon final emissionarguments/rawArguments:function_callitems ingetItemsStream()exposearguments(healed parsed object, always safe) andrawArguments(raw accumulated JSON string)Test plan
requireApprovalandstate, notexecute: falseisCompleteandarguments/rawArguments