@letta-ai/letta-agent-sdk 0.3.2 → 0.3.3

package/AGENTS.md

@@ -0,0 +1,47 @@
+# Letta Agent SDK contributor map
+
+## Canonical source
+
+Work in `src/`. `dist/` is generated by `bun run build`, ignored by Git, and
+published as a bundle. A repeated class or method in `dist/index.js` or
+`dist/client-entry.js` can represent separate source-layer responsibilities
+that Bun placed in one file; trace it back to `src/` before changing it.
+
+## Session architecture
+
+- `client-base.ts` selects the backend and constructs a session.
+- Remote, Cloud, and the default local app-server path share
+  `remote-client-session-core.ts`.
+- `remote-session-protocol.ts` owns portable protocol types, validation, and
+  wire-to-domain normalization.
+- `remote-turn-coordinator.ts` owns active/queued turn correlation and the
+  `SDKMessage` stream queue.
+- `app-server-session.ts` adapts an app-server connection to the runtime
+  controller used by the portable session core.
+- `cloud-session.ts` resolves Cloud runtimes and managed sandboxes, then uses
+  the same runtime controller and portable session core.
+- `session.ts` is the separate legacy stdio implementation used only when
+  `transport: "stdio"` is selected and by the historical agent-less
+  `createSession()` helper.
+- `types.ts` defines the stable public SDK surface. Internal protocol types
+  belong beside their implementation rather than in the public type barrel.
+
+For `session.listMessages()` on an app-server or Cloud session, the call path
+is:
+
+`RemoteClientSessionCore.listMessages` →
+`RemoteClientRuntimeController.listMessages` →
+the selected transport adapter.
+
+Those methods operate at different layers and should not be combined merely
+because they share a name.
+
+## Change discipline
+
+- Keep transport parsing out of the session facade.
+- Keep turn correlation and stream buffering in `RemoteTurnCoordinator`.
+- Preserve exports from the package root and `/client` unless a change is
+  explicitly intended to be breaking.
+- Treat source-size exceptions in `scripts/check-source-size.ts` as debt
+  ceilings: reduce them when a file shrinks and do not raise them casually.
+- Run `bun run check`, `bun test`, and `bun run build` before opening a PR.

package/README.md

@@ -108,6 +108,23 @@ await using session = client.createSession(agentId, {
 });
 ```
 
+### Managed Cloud sandbox repositories
+
+Cloud sessions can clone up to 10 GitHub repositories into the managed
+sandbox. Public repositories clone directly; private repositories require
+access through the organization's GitHub integration.
+
+```ts
+await using session = client.createSession(agentId, {
+  sandbox: {
+    githubRepositories: [
+      { owner: "letta-ai", repo: "letta-docs-md" },
+      { owner: "letta-ai", repo: "letta-code" },
+    ],
+  },
+});
+```
+
 ### Remote App Server
 
 ```ts