Skip to content

feat: add host file and artifact service contracts - #709

Merged
danny-avila merged 2 commits into
mainfrom
danny-avila/sdk-host-files
Nov 18, 2026
Merged

danny-avila merged 2 commits into
mainfrom
danny-avila/sdk-host-files

Conversation

@danny-avila

@danny-avila danny-avila commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

SDK/custom graphs have host-model and host-tool boundaries, but no reusable interface for authorized attachment reads or generated file publication. This adds a versioned file service that can use a host's existing storage directly or through an authenticated transport. It keeps storage credentials, paths, download authorization and publication ownership on the host.

Graphs receive opaque references pinned to immutable revisions. Reads pull bounded ranges; uploads stream into private staging with exact length and host-computed SHA-256 verification. A separate publication request enters the host's native file/event pipeline. Shared admission bounds concurrent operations and chunk-copy reservations; cancelled/timed-out work remains charged until storage and input cleanup settle.

Ownership

custom graph
  createHostFileBindings
    HostFileService (direct or transport adapter)
      createHostFileService
        authenticated identity + limits + cancellation
          existing authorized host storage / publication

The SDK validates identity assertions and protocol data. The transport authenticates callers; the storage adapter rechecks canonical ACLs/revisions and owns durable operation-ID reconciliation, storage quotas, private-file cleanup and native attachment events. Mutation retries are never automatic; timeout does not prove a publication failed to commit.

Verification

  • 215 tests across all nine harness suites passed.
  • New coverage includes identity dimensions, stale/mismatched reads, capability/version negotiation, size/hash validation, shared admission, cancellation/timeouts, late cleanup and sanitized errors.
  • A conditional LangGraph graph exercises read → transform → stage → publish over real loopback HTTP and filesystem storage, including repeated publication and forbidden references.
  • TypeScript, scoped ESLint/Prettier/import checks and circular-dependency check passed.
  • Production CJS/ESM/declaration build passed. Both built entry points expose the new API, and the package includes its declarations.

Scope and rollout

This is the completed SDK contract/helper slice. It does not activate LibreChat's production remote file transport, provide a durable storage implementation, or establish native UI/latency parity. The HTTP test adapter and receipt map are conformance fixtures. Sandbox session mounts, provider-specific multimodal encoding, rich rendered UI artifacts and automatic child grants remain separate integrations.

The version remains 4.2.9. Release changes belong in a separate PR, followed by LibreChat adapters using the existing attachment, snapshot, publication and download services. No existing graph/model/tool execution behavior changes.

Related: LibreChat-AI/LibreChat#18400. Contract and host integration obligations are documented in src/harness/files.md.

Copy link
Copy Markdown
Collaborator Author

@codex review

Please review the current PR head a8e09e1. Confirm that this exact commit is the reviewed commit and ignore findings that apply only to earlier heads.

Focus on identity/reference boundaries, chunk and aggregate resource limits, cancellation and retained cleanup, partial uploads, error disclosure, publication/retry semantics, and whether the storage/transport obligations are explicit enough for the subsequent LibreChat adapter.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-18T12:31:59.751358Z 656b7ae Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a8e09e1d94

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/harness/fileStream.ts Resolved

Copy link
Copy Markdown
Collaborator Author

@codex review

Please review the current PR head 656b7ae. Confirm that this exact commit is the reviewed commit and ignore findings that apply only to earlier heads.

The upload wrapper now explicitly forwards return/throw cleanup even before its first next(). The regression covers binding → host service → early store rejection → blocked producer cleanup, verifying that timeout returns while the host reservation remains charged until cleanup drains. Publication receipts also recheck the negotiated size limit at the transport consumer. The harness suite, typecheck, scoped lint and production build pass.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: 656b7ae101

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@danny-avila danny-avila mentioned this pull request Nov 18, 2026
@danny-avila
danny-avila merged commit e07a1d3 into main Nov 18, 2026
13 checks passed
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