feat: add agentworks invocation support

[rhinchey-cs]

Summary

Adds a new agentWorks API to Foundry-JS for invoking AgentWorks agents and consuming their responses as a stream. Unlike the existing request/response bridge calls that resolve to a single payload, agent invocations stream many chunks over a single message correlation ID, terminated by a complete or error.

What's included

• AgentWorks / AgentStream abstraction (src/abstraction/agent-works.ts) — api.agentWorks.invoke(agentId, params)
  returns an AgentStream that emits:

  • data — each chunk as it arrives
  • end — stream completed successfully
  • error — stream terminated with an error

  Streams support on()/off() subscription and abort() to cancel an in-flight invocation. The parent AgentWorks
  instance tracks open streams and tears them all down on destroy().

• Streaming bridge primitives (src/bridge.ts) — adds openStream() and sendStreamMessage(). Unlike postMessage(), a stream subscription is not removed after the first response; it persists for the lifetime of the stream and is removed via the returned close() once the stream completes, errors, or is aborted. No timeout is applied since streams can run for arbitrary durations. The abort request reuses the original invoke message ID to correlate the cancellation.

• Message types (src/types.ts) — adds the agentWorks message type, AgentWorksInvokeParams,
  AgentWorksRequestMessage (invoke / abort), and AgentWorksResponseMessage (chunk / complete / error), wired into
  the RequestMessage/ResponseMessage unions and ResponseFor mapping.

• Public exports (src/index.ts) — exports AgentWorks and AgentStream.

• Docs & tests — new README section under "Working with AgentWorks" and unit tests in
  tests/abstraction/agent-works.test.ts.

Usage

const stream = falcon.agentWorks.invoke('<agent-id>', { prompt: 'Summarize this detection' });

stream.on('data', (chunk) => {
  // append chunk to your UI
});

stream.on('end', () => {
  // finalize output
});

stream.on('error', (err) => {
  // handle err.message
});

// cancel an in-flight stream early
stream.abort();

[changeset-bot]

⚠️ No Changeset found

Latest commit: ba17103

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR