runwork 0.27.1 → 0.28.0

package/README.md

@@ -8,7 +8,7 @@ Runwork is an AI workspace that brings AI agents, custom apps, and human teams i
 
 This CLI is the local development interface to the platform. You write TypeScript, and the platform handles deployment, infrastructure, AI, and integrations:
 
-- **Full-stack apps, zero infrastructure** -- Data storage, file hosting, background jobs, durable workflows, AI, and 3,200+ third-party integrations are all built into the platform. You write application code; Runwork runs it.
+- **Full-stack apps, zero infrastructure** -- Data storage, file hosting, background jobs, durable workflows, AI, and thousands of third-party integrations are all built into the platform. You write application code; Runwork runs it.
 - **Zero to app in seconds** -- Describe what you need and Runwork generates it. Developers customize with code using the [`@runworkai/framework`](https://www.npmjs.com/package/@runworkai/framework).
 - **Instant deployments** -- Push code and get a live URL. Preview environments while you develop, production at the edge.
 - **Built-in AI agents** -- Conversational agents that read data, take actions, and coordinate across apps. No API keys or model configuration to manage.
@@ -57,6 +57,7 @@ runwork dev            # Start developing with live preview
 | `runwork clone` | Clone an existing Runwork app to your machine |
 | `runwork dev` | Start local development with live preview and auto-sync |
 | `runwork deploy` | Deploy to production |
+| `runwork spaces` | Spaces: containers for one kind of work |
 | `runwork logout` | Remove stored credentials |
 
 ### `runwork dev`
@@ -72,6 +73,64 @@ The main development command. When you run `runwork dev`:
 
 Edit files in your editor, and changes appear in the preview automatically.
 
+Preview data lives inside the sandbox. Every entity starts empty again after the sandbox is
+replaced, which a restart or a recycled container can both do. Your production data is untouched.
+
+### `runwork spaces`
+
+A space is a container for one kind of work: its files, AI instructions, skills, apps, automations
+and conversations. `runwork spaces map` keeps a local folder in a space, so what you share is
+uploaded for members of the space to read and conversations you run there are filed under the space
+on this machine.
+
+| Subcommand | Description |
+|------------|-------------|
+| `spaces suggest` | Propose spaces and things to keep in them from your local conversations (nothing is uploaded) |
+| `spaces list` | Spaces in the workspace, with the folders on this machine mapped to each |
+| `spaces map <folder>` | Keep a folder in a space: everything in it waits in Changes for you to share, and what you share is uploaded for members of the space to read. Conversations you run there are filed under the space on this machine, not uploaded |
+| `spaces scope <folder>` | What a folder would share with a space, before you map it. Maps nothing and writes nothing |
+| `spaces create <name>` | Create a space |
+| `spaces default-folder [space]` | Where this space's folder would go on this machine if nobody chose. Creates nothing and maps nothing. |
+| `spaces contents [space]` | What is filed under a space: its apps, skills, chats, workflows and endpoints |
+| `spaces ls [space] [path]` | The files a space holds, as a teammate on another machine would see them |
+| `spaces cat [space] <path>` | Print a file the space holds, as it is now or as it was at an earlier commit |
+| `spaces history [space] <path>` | Who changed a file in a space and when, newest first, with the commit each version can be read at |
+| `spaces put [space] <path> [file]` | Write any file into a space, from a local file or from stdin |
+| `spaces rm [space] <path>` | Take a file out of a space. Its history stays, so a teammate can still see what it was. |
+| `spaces instructions [space] [file]` | Read a space's `AGENTS.md`, or replace it from a local file or stdin |
+| `spaces files [path]` | What is in a mapped folder, and which of it the space shares |
+| `spaces include <path>` | Share a file or folder from a mapped folder with its space |
+| `spaces exclude <path...>` | Stop sharing a file or folder, and take it out of the space |
+| `spaces pause <folder>` | Stop this folder sharing on its own: its changes wait for runwork spaces share. Teammates' changes still arrive |
+| `spaces resume <folder>` | Let this folder share its changes on its own, as each file stops changing |
+| `spaces changes [folder]` | What this folder would send to its space next, and what is holding each of it back |
+| `spaces sync [folder]` | Bring mapped folders and their spaces together: commit local changes, push, and pull what teammates added (no system git needed). With no folder named it syncs the mapped folder you are standing in; `--all` syncs every one of them |
+| `spaces share [folder] [path...]` | Share what is waiting in a mapped folder now, without waiting for files to settle. Name any number of paths to share exactly those |
+| `spaces launched <folder>` | Record that a conversation was just opened from this folder's space, so a cloud session with several space folders connected knows which one this is about |
+| `spaces unmap <folder>` | Stop filing a folder under a space (this machine only) |
+| `spaces reset <folder>` | Throw away this machine's copy of a mapped folder's space history, so the next sync rebuilds it from the space |
+| `spaces prune` | Remove space histories on this machine that no folder maps to any more |
+| `spaces mappings` | Folder-to-space mappings on this machine, the one you are standing in first |
+
+`spaces rm` is also available as `spaces delete`. A mapped folder shares nothing until you ask for
+it: run `spaces changes` to see what is waiting and `spaces share` to send it. Pass `--auto` to
+`spaces map`, or run `spaces resume`, to have a folder share each file on its own once the file
+stops changing.
+
+Anything that files something under a space takes that space from the folder you are in when it is
+mapped to one: `init`, `skills push`, `skills install`, `save-convo` and `share-convo`. `--space`
+always wins, and each of them says which space it chose and why.
+
+The verbs above that act on a space take it the same way, so inside a mapped folder `spaces ls`,
+`spaces cat notes/plan.md` and `spaces contents` are about that folder's space. Naming the space
+still works everywhere and still wins. How many arguments you give decides what they mean, so an
+existing command keeps meaning what it always did: one argument to `ls` and `instructions` is the
+space, and two to `put` are the space and the path. `cat`, `history` and `rm` read a single argument
+as the path, and `put` takes the space from the folder when it is given a path alone, with the
+content piped in (`runwork spaces put notes/plan.md < ./plan.md`). Reading falls back to your
+personal space when the folder is mapped to nothing; `put`, `rm` and `instructions` ask you to name
+one instead, because a write must not land somewhere nobody pointed at.
+
 ## How It Works
 
 Runwork apps are full-stack TypeScript projects built with the [`@runworkai/framework`](https://www.npmjs.com/package/@runworkai/framework). The CLI handles the development lifecycle:
@@ -93,7 +152,7 @@ Every Runwork app gets built-in access to:
 - **File storage** -- Upload and manage files and media
 - **Public endpoints** -- Authenticated APIs for external consumers
 - **Cross-app workspaces** -- Shared entities, channels, and notifications between apps
-- **3,200+ integrations** -- OAuth-managed connections to third-party services
+- **Third-party integrations** -- OAuth-managed connections to third-party services
 
 ## Project Structure
 

package/bundled-types/channels.d.ts

@@ -1,2 +1,19 @@
+/**
+ * Barrel: `@runworkai/framework/channels` (retired).
+ *
+ * Kept so apps built against earlier versions keep compiling. The notices below
+ * are JSDoc rather than line comments on purpose: tsc drops `//` comments from
+ * the emitted `.d.ts`, and these declarations are what every local agent reads
+ * out of `.runwork/types/`.
+ */
+/**
+ * @deprecated Channels are retired. This still posts to the workspace event
+ * stream, where the message appears in the activity feed and on the app's
+ * timeline, so deployed apps keep working. Use `emitEvent` from
+ * `@runworkai/framework/events` for new code.
+ */
 export { postToChannel } from './core-channels';
+/**
+ * @deprecated Channels are retired; see `postToChannel`.
+ */
 export type { PostToChannelParams } from './core-channels';

package/bundled-types/core-channels.d.ts

@@ -1,15 +1,17 @@
 /**
- * Core Channels
+ * Core Channels (retired)
  * DO NOT MODIFY THIS FILE - You may break the project functionality
  *
- * This module provides:
- * - postToChannel(): Post rich markdown messages to workspace channels
- *
- * Channels are auto-created if they don't exist, with automatic app event filtering.
+ * Workspace channels no longer exist. This module stays only so apps built
+ * against earlier framework versions keep working: `postToChannel()` still
+ * sends its message to the platform, which files it as an app event in the
+ * workspace activity feed and on the app's timeline. New code should call
+ * `emitEvent()` from `@runworkai/framework/events` instead.
  * When running outside a workspace (standalone mode), calls are silently skipped.
  */
+/** @deprecated Channels are retired; use `emitEvent()` from `@runworkai/framework/events`. */
 export interface PostToChannelParams {
-    /** Channel name (e.g., "#inventory-alerts" or "inventory-alerts"). Auto-normalized: # stripped, lowercased, trimmed. */
+    /** Former channel name; kept for compatibility and ignored by the platform. */
     channel: string;
     /** Markdown message content */
     content: string;
@@ -31,12 +33,11 @@ interface ChannelEnv {
  */
 type WaitUntilContext = Pick<ExecutionContext, 'waitUntil'>;
 /**
- * Post a rich markdown message to a workspace channel.
+ * @deprecated Channels are retired. The message is still delivered as an app
+ * event that appears in the workspace activity feed and on the app's timeline;
+ * use `emitEvent()` from `@runworkai/framework/events` for new code.
  * Fire-and-forget: uses ctx.waitUntil so it doesn't block the response.
  * Silently skips if workspace env vars are not configured (standalone mode).
- *
- * Channels are auto-created on first use. The channel will automatically
- * include this app's system events via filter projection.
  */
 export declare function postToChannel(ctx: WaitUntilContext, env: ChannelEnv, params: PostToChannelParams): void;
 export {};

package/bundled-types/core-events.d.ts

@@ -6,7 +6,7 @@
  * - emitEvent(): Fire-and-forget event emission to the workspace event stream
  * - flog(): Structured logging that outputs JSON to sandbox stdout
  *
- * Events appear in the workspace activity feed and channel views.
+ * Events appear in the workspace activity feed and on the app's timeline.
  * When running outside a workspace (standalone mode), calls are silently skipped.
  */
 export interface EmitEventParams {
@@ -31,7 +31,8 @@ interface EventEnv {
  */
 type WaitUntilContext = Pick<ExecutionContext, 'waitUntil'>;
 /**
- * Convert an app name to a kebab-case channel name.
+ * Convert an app name to the kebab-case label the legacy `channel` field carries.
+ * @deprecated Channels are retired; the platform ignores the field.
  * "My Cool App" -> "my-cool-app"
  */
 export declare function toChannelName(appName: string): string;

package/bundled-types/core-workspace.d.ts

@@ -89,6 +89,15 @@ export interface RegisterEntityRequest extends Record<string, unknown> {
     schema?: Record<string, unknown>;
     deploymentMode?: 'preview' | 'production';
 }
+export interface RegisterAllEntitiesRequest extends Record<string, unknown> {
+    appId: string;
+    appName: string;
+    entities: Array<{
+        entityName: string;
+        schema?: Record<string, unknown>;
+    }>;
+    deploymentMode?: 'preview' | 'production';
+}
 export interface RegisterAppRequest extends Record<string, unknown> {
     appId: string;
     appName: string;
@@ -269,6 +278,19 @@ export declare class WorkspaceContext {
      * Register an entity with the workspace so other apps can query it
      */
     registerEntity(entityName: string, schema?: Record<string, unknown>): Promise<void>;
+    /**
+     * Register every entity this app defines in one call.
+     *
+     * Ownership rules are the same as registerEntity (first registrant owns,
+     * later apps are recorded as references, preview never touches production),
+     * but the workspace applies them in a single state write instead of one per
+     * entity. A platform that predates the bulk route answers 404; then each
+     * entity is registered individually so an older platform keeps working.
+     */
+    registerAllEntities(entities: Array<{
+        entityName: string;
+        schema?: Record<string, unknown>;
+    }>): Promise<void>;
     /**
      * Register this app with the workspace (safe to call multiple times)
      */
@@ -545,3 +567,9 @@ export declare function deleteWorkspaceEntity(env: Env, entityName: string, id:
  * Called once when the worker starts
  */
 export declare function initializeWorkspace(env: Env): Promise<void>;
+/**
+ * Forget that this isolate is initialized so the next request runs a sweep
+ * again. The last successful fingerprint is kept: a sweep that finds the
+ * definitions unchanged completes without calling the workspace.
+ */
+export declare function invalidateWorkspaceInitialization(): void;