@flue/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,200 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an
+      information on the current year for the copyright.
+
+      Copyright [yyyy] [name of copyright owner]
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied. See the License for the specific language governing
+      permissions and limitations under the License.

package/README.md

@@ -0,0 +1,194 @@
+# flue
+
+> **Experimental** — Flue is under active development. APIs may change.
+
+Agent framework where agents are directories compiled into deployable server artifacts.
+
+## Packages
+
+| Package                                   | Description                                |
+| ----------------------------------------- | ------------------------------------------ |
+| [`@flue/sdk`](packages/sdk)               | Core SDK: build system, sessions, tools    |
+| [`@flue/cli`](packages/cli)               | CLI for building and running agents        |
+| [`@flue/connectors`](packages/connectors) | Third-party connectors for sandboxes, etc. |
+
+## Examples
+
+### Quickstart
+
+The simplest agent — no container, no tools, just a prompt and a typed result.
+
+```ts
+// .flue/agents/hello-world.ts
+import type { FlueContext } from '@flue/sdk/client';
+import * as v from 'valibot';
+
+// Every agent needs a trigger. This agent is invoked as an API endpoint, via HTTP.
+export const triggers = { webhook: true };
+
+// The agent handler. Where the orchestration of the agent lives.
+export default async function ({ init, payload, sessionId }: FlueContext) {
+  // `session` -- Your session with the agent, including sandbox, message history, etc.
+  // By default, calling `init()` with no arguments gets you a completely empty agent,
+  // with no skills, AGENTS.md, or files.
+  const session = await init();
+
+  // prompt() sends a message in the session, triggering action.
+  // You can pass a schema to `result` to get typed, validated JSON back.
+  const result = await session.prompt(`Translate this to ${payload.language}: "${payload.text}"`, {
+    result: v.object({
+      translation: v.string(),
+      confidence: v.picklist(['low', 'medium', 'high']),
+    }),
+  });
+
+  return result;
+}
+```
+
+### Support Agent
+
+A support agent, also running in a virtual sandbox but now with an R2 bucket mounted as its file-system. The knowledge base is stored in R2 and mounted directly into the agent's filesystem — the agent searches it with its built-in tools (grep, glob, read).
+
+Session message history and file-system state are automatically persisted using Durable Objects (Cloudflare only). So you can revisit this session days, weeks, or years later and pick up where you left off automatically.
+
+```ts
+// .flue/agents/support.ts
+import { getVirtualSandbox } from '@flue/sdk/cloudflare';
+import type { FlueContext } from '@flue/sdk/client';
+import * as v from 'valibot';
+
+export const triggers = { webhook: true };
+
+export default async function ({ init, payload, env }: FlueContext) {
+  // Mount the R2 knowledge base bucket as the agent's filesystem.
+  // The agent can grep, glob, and read articles with bash, but
+  // without needing to spin up an entire container sandbox.
+  const sandbox = await getVirtualSandbox(env.KNOWLEDGE_BASE);
+  const session = await init({ sandbox });
+
+  return await session.prompt(
+    `You are a support agent. Search the knowledge base for articles
+    relevant to this request, then write a helpful response.
+
+    Customer: ${payload.message}`,
+  );
+}
+```
+
+### Issue Triage (CI)
+
+A triage agent that runs whenever a new issue is opened (or commented on) on GitHub, running on GitHub Actions.
+
+Flue was designed to power CI workflows since day one. The `"local"` filesystem sandbox enables two things:
+
+1. Mount the current directory to your virtual file system.
+2. Connect privileged CLIs to your agent (`gh`, `glab`, `git`) without leaking sensitive keys and secrets.
+
+```ts
+// .flue/agents/triage.ts
+import { defineCommand, type FlueContext } from '@flue/sdk/client';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import * as v from 'valibot';
+
+export const triggers = {};
+
+// Connect privileged CLIs to your agent without leaking sensitive keys and secrets.
+// Secrets are hooked up inside the command definition here, so your agent never sees them.
+// Commands are controlled per-prompt, so you can be as granular with access as you need.
+const npm = defineCommand('npm', async (args) => promisify(execFile)('npm', args));
+const gh = defineCommand('gh', async (args) =>
+  promisify(execFile)('gh', args, {
+    env: { GH_TOKEN: process.env.GH_TOKEN },
+  }),
+);
+
+export default async function ({ init, payload }: FlueContext) {
+  // 'local' mounts the host filesystem at /workspace — ideal for CI
+  // where the repo is already checked out. Skills and AGENTS.md are
+  // discovered automatically from the workspace directory.
+  const session = await init({ sandbox: 'local' });
+
+  const result = await session.skill('triage', {
+    // Pass arguments to any prompt or skill.
+    args: { issueNumber: payload.issueNumber },
+    // Grant access to `gh` and `npm` for the life of this skill.
+    commands: [gh, npm],
+    // Provide roles (aka subagents) to guide your agent. Defined in .flue/roles/
+    role: 'triager',
+    // Result schemas are great for being able to act/orchestrate
+    // based on the result of your prompt or skill call.
+    result: v.object({
+      severity: v.picklist(['low', 'medium', 'high', 'critical']),
+      reproducible: v.boolean(),
+      summary: v.string(),
+      fix_applied: v.boolean(),
+    }),
+  });
+
+  return result;
+}
+```
+
+### Coding Agent (Container Sandbox)
+
+The examples above all run on a lightweight virtual sandbox — no container needed. But for a full coding agent, you want a real Linux environment with git, Node.js, a browser, and a cloned repo ready to go.
+
+Daytona's declarative image builder lets you define the environment in code. The image is cached after the first build, so subsequent sessions start instantly.
+
+```ts
+// .flue/agents/code.ts
+import { Type, type FlueContext, type ToolDef } from '@flue/sdk/client';
+import { Daytona } from '@daytona/sdk';
+import { daytona } from '@flue/connectors/daytona';
+
+export const triggers = { webhook: true };
+
+export default async function ({ init, payload, env }: FlueContext) {
+  // Each session gets a real container via Daytona. The container has
+  // a full Linux environment with persistent filesystem and shell.
+  //
+  // For simplicity, we always create a new sandbox here. You could also
+  // first check for an existing sandbox for the sessionId, and reuse that
+  // instead to best pick up where you last left off in the conversation.
+  const client = new Daytona({ apiKey: env.DAYTONA_API_KEY });
+  const sandbox = await client.create();
+  const session = await init({
+    sandbox: daytona(sandbox, { cleanup: true }),
+  });
+
+  // For simplicity, we clone the target repo into the sandbox here.
+  // You could also bake these into the container image snapshot for a
+  // faster / near-instant startup.
+  await session.shell(`git clone ${payload.repo} /workspace/project`);
+  await session.shell('npm install', { cwd: '/workspace/project' });
+
+  // Coding agents don't hide the agent DX from the user, so no need to
+  // wrap the user's prompt in anything. Just send it to the agent directly
+  // and then stream back the progress and final results.
+  return await session.prompt(payload.prompt);
+}
+```
+
+## Running Agents
+
+### Trigger From the CLI
+
+Build and run any agent locally, perfect for fast local testing or running in CI.
+
+```bash
+flue run hello --target node --session-id test-1 \
+  --payload '{"text": "Hello world", "language": "French"}'
+```
+
+### Trigger From HTTP Endpoint
+
+Build and deploy your agents as a web server, perfect for hosted agents.
+
+`flue build` builds to a `./dist` directory, which you can then deploy anywhere. Cloudflare and any Node.js host are supported today, with more coming in the future.
+
+```
+flue build --target node          # Node.js server
+flue build --target cloudflare    # Cloudflare Workers + Durable Objects
+```

package/dist/client.d.mts

@@ -0,0 +1,30 @@
+import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, b as SessionEnv, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, l as CommandSupport, m as FlueSession, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-xNvqlohs.mjs";
+import { Type } from "@mariozechner/pi-ai";
+
+//#region src/client.d.ts
+interface FlueContextConfig {
+  sessionId: string;
+  payload: any;
+  env: Record<string, any>;
+  agentConfig: AgentConfig;
+  createDefaultEnv: () => Promise<SessionEnv>;
+  createLocalEnv: () => Promise<SessionEnv>;
+  defaultStore: SessionStore;
+  /**
+   * Platform-specific sandbox resolver hook. Called before default resolution.
+   * Returns SessionEnv to use, or null to fall through to default logic.
+   */
+  resolveSandbox?: (sandbox: unknown) => Promise<SessionEnv> | null;
+}
+/** Extends FlueContext with server-only methods. Agent handlers only see FlueContext. */
+interface FlueContextInternal extends FlueContext {
+  setEventCallback(callback: FlueEventCallback | undefined): void;
+}
+declare function createFlueContext(config: FlueContextConfig): FlueContextInternal;
+declare function defineCommand(name: string, execute: (args: string[]) => Promise<{
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}>): Command;
+//#endregion
+export { type BashLike, type Command, type CommandSupport, type FileStat, type FlueContext, FlueContextConfig, FlueContextInternal, type FlueEvent, type FlueEventCallback, type FlueSession, type PromptOptions, type PromptResponse, type SandboxFactory, type SessionData, type SessionEnv, type SessionInit, type SessionStore, type ShellOptions, type ShellResult, type SkillOptions, type TaskOptions, type ToolDef, Type, createFlueContext, defineCommand };

package/dist/client.mjs

@@ -0,0 +1,62 @@
+import { n as Session, o as discoverSessionContext } from "./session-BD0MEuO3.mjs";
+import { bashToSessionEnv } from "./sandbox.mjs";
+import { Type } from "@mariozechner/pi-ai";
+
+//#region src/client.ts
+function createFlueContext(config) {
+	let initialized = false;
+	let currentEventCallback;
+	return {
+		get sessionId() {
+			return config.sessionId;
+		},
+		get payload() {
+			return config.payload;
+		},
+		get env() {
+			return config.env;
+		},
+		async init(options) {
+			if (initialized) throw new Error("[flue] init() can only be called once per request.");
+			initialized = true;
+			const sandbox = options?.sandbox;
+			const env = await resolveSessionEnv(config.sessionId, sandbox, config);
+			const store = options?.persist ?? config.defaultStore;
+			const savedData = await store.load(config.sessionId);
+			const localContext = await discoverSessionContext(env);
+			const sessionConfig = {
+				...config.agentConfig,
+				systemPrompt: localContext.systemPrompt,
+				skills: localContext.skills
+			};
+			return new Session(config.sessionId, sessionConfig, env, store, savedData, currentEventCallback);
+		},
+		setEventCallback(callback) {
+			currentEventCallback = callback;
+		}
+	};
+}
+/** Duck-type detection for just-bash Bash instances. */
+function isBashLike(value) {
+	return typeof value === "object" && value !== null && "exec" in value && "getCwd" in value && "fs" in value && typeof value.exec === "function" && typeof value.getCwd === "function" && typeof value.fs === "object";
+}
+/** Resolve sandbox option to SessionEnv: empty → local → BashLike → platform hook → SandboxFactory. */
+async function resolveSessionEnv(sessionId, sandbox, config) {
+	if (sandbox === void 0 || sandbox === "empty") return config.createDefaultEnv();
+	if (sandbox === "local") return config.createLocalEnv();
+	if (isBashLike(sandbox)) return bashToSessionEnv(sandbox);
+	if (config.resolveSandbox) {
+		const resolved = await config.resolveSandbox(sandbox);
+		if (resolved) return resolved;
+	}
+	return sandbox.createSessionEnv({ sessionId });
+}
+function defineCommand(name, execute) {
+	return {
+		name,
+		execute
+	};
+}
+
+//#endregion
+export { Type, createFlueContext, defineCommand };

package/dist/cloudflare/index.d.mts

@@ -0,0 +1,36 @@
+import { S as SessionStore, b as SessionEnv } from "../types-xNvqlohs.mjs";
+
+//#region src/cloudflare/virtual-sandbox.d.ts
+interface VirtualSandboxOptions {
+  /** R2 key prefix for session isolation. */
+  prefix?: string;
+}
+declare function getVirtualSandbox(): Promise<any>;
+declare function getVirtualSandbox(bucket: unknown, options?: VirtualSandboxOptions): Promise<any>;
+//#endregion
+//#region src/cloudflare/cf-sandbox.d.ts
+declare function cfSandboxToSessionEnv(sandbox: any, cwd?: string): Promise<SessionEnv>;
+//#endregion
+//#region src/cloudflare/session-store.d.ts
+declare function store(): SessionStore;
+//#endregion
+//#region src/cloudflare/context.d.ts
+/**
+ * Cloudflare environment context injection. Safe because each DO is single-threaded.
+ * Set before handler invocation, accessed by runtime primitives, cleared after.
+ */
+interface CloudflareContext {
+  env: Record<string, any>;
+  agentInstance: {
+    state: any;
+    setState(state: any): void;
+  };
+  storage: {
+    sql: any;
+  };
+}
+declare function setCloudflareContext(ctx: CloudflareContext): void;
+declare function getCloudflareContext(): CloudflareContext;
+declare function clearCloudflareContext(): void;
+//#endregion
+export { type CloudflareContext, type VirtualSandboxOptions, cfSandboxToSessionEnv, clearCloudflareContext, getCloudflareContext, getVirtualSandbox, setCloudflareContext, store };