@playcraft/cli 0.1.59-beta → 0.1.60-beta

package/dist/workspace-runtime/codex/app-server.js

@@ -19,6 +19,7 @@ import { readNativeThreadImage } from './thread-image.js';
 import { WORKSPACE_UI_TOOLS, WorkspaceUiTools } from './ui-tools.js';
 import { WORKSPACE_DELIVERY_TOOLS, WorkspaceDeliveryTools, isWorkspaceDeliveryTool } from './delivery-tools.js';
 import { WORKSPACE_UI_INSTRUCTIONS } from './ui-instructions.js';
+import { WORKSPACE_SCHEDULED_TASK_TOOLS, WorkspaceScheduledTaskTools, isWorkspaceScheduledTaskTool } from './scheduled-task-tools.js';
 function withModelShell(config, modelConfigId) {
     if (!modelConfigId || !/^[0-9a-f-]{36}$/i.test(modelConfigId))
         return config;
@@ -191,9 +192,13 @@ export function createCodexAppServerAdapter(options) {
     const coordinatorDirectories = new Map();
     const uiTools = new WorkspaceUiTools(emitCollected, options.uiToolTimeoutMs);
     const deliveryTools = options.deliveryTools ? new WorkspaceDeliveryTools(options.deliveryTools) : undefined;
+    const scheduledTaskTools = options.scheduledTaskProposals ? new WorkspaceScheduledTaskTools(options.scheduledTaskProposals, (proposalId, source) => emitCollected(collectedEvent('notification', 'scheduled-task.proposal.changed', {
+        proposalId, sessionId: threads.get(source.threadId)?.sessionId, threadId: source.threadId, turnId: source.turnId,
+    }))) : undefined;
     const dynamicTools = [
         ...(options.workspaceUi ? WORKSPACE_UI_TOOLS : []),
         ...(deliveryTools ? WORKSPACE_DELIVERY_TOOLS : []),
+        ...(scheduledTaskTools ? WORKSPACE_SCHEDULED_TASK_TOOLS : []),
     ];
     function emitCollected(event) {
         for (const listener of collected)
@@ -609,6 +614,26 @@ export function createCodexAppServerAdapter(options) {
             }
             if (method === 'item/tool/call') {
                 const thread = typeof payload.threadId === 'string' ? threads.get(payload.threadId) : undefined;
+                if (scheduledTaskTools && isWorkspaceScheduledTaskTool(payload.tool)) {
+                    const threadId = String(payload.threadId ?? ''), turnId = String(payload.turnId ?? '');
+                    const current = () => {
+                        try {
+                            return Boolean(thread && threads.get(threadId) === thread && thread.turnActive
+                                && thread.lastTurnId === turnId && !childParents.has(threadId)
+                                && ['execute', 'plan'].includes(thread.activeMode ?? '') && !options.fixedExecution
+                                && !options.trustedExecution?.(thread.sessionId));
+                        }
+                        catch {
+                            return false;
+                        }
+                    };
+                    setTimeout(() => {
+                        void scheduledTaskTools.request(id, payload, nativeClient, thread ? {
+                            bridge: thread.scheduledTaskProposalBridge, threadId, turnId, current,
+                        } : undefined);
+                    }, 0);
+                    return;
+                }
                 if (deliveryTools && isWorkspaceDeliveryTool(payload.tool)) {
                     void deliveryTools.request(id, payload, nativeClient, {
                         sessionId: thread?.sessionId,
@@ -734,6 +759,7 @@ export function createCodexAppServerAdapter(options) {
         name: 'codex-app-server',
         workspaceUi: options.workspaceUi === true,
         ready: () => readyFlag && !closed,
+        ...(scheduledTaskTools ? { scheduledTaskProposalSource: (source) => scheduledTaskTools.isActive(source) } : {}),
         executionProcess() {
             if (!live)
                 return undefined;
@@ -927,7 +953,7 @@ export function createCodexAppServerAdapter(options) {
                 selectedModel ??= thread.resolvedModel ?? model;
                 const requestId = rpc.reserveRequest();
                 await input.persistReservation({ nativeRequestId: String(requestId), modelConfigId, reasoningEffort, permissionMode });
-                activateModel();
+                activateModel(execution.sandboxPolicy.type === 'readOnly');
                 thread.modelConfigId = modelConfigId;
                 thread.reasoningEffort = reasoningEffort;
                 thread.permissionMode = permissionMode;
@@ -941,6 +967,7 @@ export function createCodexAppServerAdapter(options) {
                     return { outcome: 'uncertain', threadId: input.threadId };
                 try {
                     thread.turnActive = true;
+                    thread.scheduledTaskProposalBridge = input.scheduledTaskProposalBridge;
                     thread.uiSnapshot = options.workspaceUi && input.uiSnapshot?.sessionId === input.sessionId ? input.uiSnapshot : undefined;
                     const started = await rpc.sendReserved(requestId, 'turn/start', { threadId: input.threadId, input: [
                             { type: 'text', text: input.text },

package/dist/workspace-runtime/codex/launcher-client.js

@@ -33,6 +33,24 @@ function request(socketPath, message) {
         });
     });
 }
+/** A persisted identity lets the controller stop development-user writers after a request ends. */
+export async function stopLauncherProcess(input) {
+    if (!input.instanceId)
+        throw new Error('launcher_start_unconfirmed');
+    const { socketPath, ...identity } = input;
+    // A new launcher's empty registry cannot confirm an old group's exit.
+    for (const signal of ['SIGTERM', 'SIGKILL']) {
+        await request(socketPath, { ...identity, action: 'stop', signal });
+        const deadline = Date.now() + 3000;
+        while (Date.now() < deadline) {
+            const status = await request(socketPath, { ...identity, action: 'status' });
+            if (status.running === false)
+                return;
+            await delay(50);
+        }
+    }
+    throw new Error('codex_group_stop_unconfirmed');
+}
 /** The private launcher owns the boundary; development shells never receive its identity. */
 export async function prepareLauncherOrigin(input) {
     try {
@@ -98,9 +116,12 @@ export async function startLauncherProcess(input) {
                 try {
                     const frame = JSON.parse(line);
                     if (!started) {
+                        if (frame.ok === false)
+                            throw Object.assign(new Error(frame.error || 'launcher_start_failed'), { launchRejected: true });
                         if (!frame.ok || !frame.pid || !frame.instanceId)
                             throw new Error(frame.error || 'launcher_start_failed');
                         identity = {
+                            socketPath: input.socketPath,
                             processId: input.processId,
                             runtimeEpoch: input.runtimeEpoch,
                             instanceId: frame.instanceId,
@@ -146,6 +167,7 @@ export async function startLauncherProcess(input) {
         });
     });
     return {
+        identity: identity,
         pid,
         stdin,
         stdout,
@@ -163,31 +185,19 @@ export async function startLauncherProcess(input) {
         },
         stop() {
             stopPromise ??= (async () => {
-                // A new launcher's empty registry cannot confirm an old group's exit.
-                for (const signal of ['SIGTERM', 'SIGKILL']) {
-                    await request(input.socketPath, { ...identity, action: 'stop', signal });
-                    const deadline = Date.now() + 3000;
-                    while (Date.now() < deadline) {
-                        const status = await request(input.socketPath, { ...identity, action: 'status' });
-                        if (status.running === false) {
-                            let timeout;
-                            try {
-                                await Promise.race([transportClosed, new Promise((_resolve, reject) => {
-                                        timeout = setTimeout(() => {
-                                            socket.destroy();
-                                            reject(new Error('launcher_output_drain_unconfirmed'));
-                                        }, 3000);
-                                    })]);
-                            }
-                            finally {
-                                clearTimeout(timeout);
-                            }
-                            return;
-                        }
-                        await delay(50);
-                    }
+                await stopLauncherProcess(identity);
+                let timeout;
+                try {
+                    await Promise.race([transportClosed, new Promise((_resolve, reject) => {
+                            timeout = setTimeout(() => {
+                                socket.destroy();
+                                reject(new Error('launcher_output_drain_unconfirmed'));
+                            }, 3000);
+                        })]);
+                }
+                finally {
+                    clearTimeout(timeout);
                 }
-                throw new Error('codex_group_stop_unconfirmed');
             })();
             return stopPromise;
         },

package/dist/workspace-runtime/codex/model-broker.js

@@ -7,6 +7,7 @@ import { z } from 'zod';
 import { workspaceContextFromRoot } from '../workspaces/registry.js';
 import { PLATFORM_ROUTES, modelResponsesPath, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
 import { WorkspaceGenerationProvenanceBroker } from './generation-provenance-broker.js';
+import { WorkspaceRemixReferencesBroker } from './remix-references-broker.js';
 const credentialSchema = z.object({
     token: z.string().min(1), expiresAt: z.string().datetime(),
     configId: z.string().uuid(), model: z.string().min(1).max(128),
@@ -27,9 +28,11 @@ export class WorkspaceModelBroker {
     requests = new Set();
     sessionRequests = new Map();
     generation;
+    references;
     constructor(state) {
         this.state = state;
         this.generation = new WorkspaceGenerationProvenanceBroker(state);
+        this.references = new WorkspaceRemixReferencesBroker(state);
     }
     async start() {
         if (this.server)
@@ -74,16 +77,37 @@ export class WorkspaceModelBroker {
         const boundaryId = sessionId && clientRequestId ? await this.generation.prepare() : undefined;
         if (!route || route.epoch !== this.state.runtimeEpoch) {
             route = { workspaceId, epoch: this.state.runtimeEpoch, capability: randomBytes(32).toString('base64url'),
-                generationCapability: randomBytes(32).toString('base64url') };
+                generationCapability: randomBytes(32).toString('base64url'), referencesCapability: randomBytes(32).toString('base64url') };
             this.routes.set(routeKey, route);
         }
         // Each session pins its prepared model; shared credential renewal cannot change an active turn.
         return {
-            activate: () => {
+            activate: (readOnly = false) => {
                 if (!this.valid(entry) || this.routes.get(routeKey) !== route)
                     throw new Error('model_access_denied');
+                const priorFeedback = route.selected?.feedback;
+                let refsBlocked = Boolean(entry.refsBlocked || priorFeedback?.refsBlocked && priorFeedback.clientRequestId === clientRequestId);
+                if (sessionId && clientRequestId) {
+                    const overlaps = (this.state.journal.listOperations?.() ?? []).some(({ operation }) => ['session.turn', 'session.review', 'session.compact'].includes(operation.kind)
+                        && ['dispatched', 'accepted', 'uncertain'].includes(operation.status)
+                        && operation.generation === this.state.config.generation && operation.runtimeEpoch === this.state.runtimeEpoch
+                        && (operation.sessionId !== sessionId || operation.clientRequestId !== clientRequestId));
+                    if (overlaps) {
+                        refsBlocked = true;
+                        // A completed overlapping turn may leave shells alive. Only a later turn gets a new safe boundary.
+                        for (const prepared of this.entries.values()) {
+                            if (prepared.epoch === this.state.runtimeEpoch)
+                                prepared.refsBlocked = true;
+                        }
+                        for (const existing of this.routes.values()) {
+                            if (existing.epoch === this.state.runtimeEpoch && existing.selected?.feedback)
+                                existing.selected.feedback.refsBlocked = true;
+                        }
+                    }
+                }
                 route.selected = { entry, model: credential.model,
-                    ...(sessionId && clientRequestId ? { feedback: { sessionId, clientRequestId, cwd, boundaryId, ...(originCwd ? { originCwd } : {}) } } : {}) };
+                    ...(sessionId && clientRequestId ? { feedback: { sessionId, clientRequestId, cwd, boundaryId, readOnly, refsBlocked,
+                            ...(originCwd ? { originCwd } : {}) } } : {}) };
             },
             model: credential.model,
             modelConfigId: credential.configId,
@@ -92,6 +116,8 @@ export class WorkspaceModelBroker {
                 ...(sessionId ? { 'shell_environment_policy.set': {
                         PLAYCRAFT_AGENT_GENERATION_ENDPOINT: `${this.baseUrl}/${routeKey}/generation-provenance`,
                         PLAYCRAFT_AGENT_GENERATION_CAPABILITY: route.generationCapability,
+                        PLAYCRAFT_REMIX_REFERENCES_ENDPOINT: `${this.baseUrl}/${routeKey}/remix-references`,
+                        PLAYCRAFT_REMIX_REFERENCES_CAPABILITY: route.referencesCapability,
                     } } : {}),
                 'model_providers.playcraft_workspace': {
                     name: 'PlayCraft Workspace', base_url: `${this.baseUrl}/${routeKey}`,
@@ -154,13 +180,15 @@ export class WorkspaceModelBroker {
         const cancel = () => abort.abort();
         response.once('close', cancel);
         try {
-            const match = /^\/([0-9a-f-]{36}(?:\/[0-9a-f]{32})?)\/(responses|generation-provenance)$/.exec(request.url ?? '');
+            const match = /^\/([0-9a-f-]{36}(?:\/[0-9a-f]{32})?)\/(responses|generation-provenance|remix-references)$/.exec(request.url ?? '');
             const route = match ? this.routes.get(match[1]) : undefined;
             const selected = route?.selected;
             const entry = selected?.entry;
             const presented = Buffer.from(request.headers.authorization ?? '');
             const generationRequest = match?.[2] === 'generation-provenance';
-            const expected = Buffer.from(route ? `Bearer ${generationRequest ? route.generationCapability : route.capability}` : '');
+            const referencesRequest = match?.[2] === 'remix-references';
+            const expected = Buffer.from(route ? `Bearer ${generationRequest ? route.generationCapability
+                : referencesRequest ? route.referencesCapability : route.capability}` : '');
             if (request.method !== 'POST' || !entry || !expected.length || presented.length !== expected.length
                 || !timingSafeEqual(presented, expected) || !this.valid(entry)) {
                 response.writeHead(403);
@@ -176,6 +204,15 @@ export class WorkspaceModelBroker {
                 await this.generation.forward(request, response, selected.feedback, () => this.valid(entry) && route?.selected === selected);
                 return;
             }
+            if (referencesRequest) {
+                if (!selected?.feedback) {
+                    response.writeHead(403);
+                    response.end();
+                    return;
+                }
+                await this.references.forward(request, response, selected.feedback, () => this.valid(entry) && route?.selected === selected);
+                return;
+            }
             activeRoute = route;
             const active = this.sessionRequests.get(route) ?? new Set();
             active.add(abort);

package/dist/workspace-runtime/codex/remix-references-broker.js

@@ -0,0 +1,184 @@
+import { realpath } from 'node:fs/promises';
+import { isAbsolute, relative } from 'node:path';
+import { z } from 'zod';
+import { PLATFORM_ROUTES, platformEndpoint, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES, WORKSPACE_REMIX_REFERENCES_MANIFEST, workspaceRemixReferenceCandidateSchema, workspaceRemixReferenceExportSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { withDirectoryWrite } from '../server/directory-access.js';
+import { wakeSourceEventUploader } from '../server/source-uploader.js';
+import { workspaceContextFromRoot } from '../workspaces/registry.js';
+import { importWorkspaceRemixReference, listWorkspaceRemixReferences } from '../workspaces/remix-references.js';
+import { shareWorkspaceGit } from '../workspaces/shared-git.js';
+import { batchDirectoryHeld } from '../batch/occupancy.js';
+import { verifyLauncherOrigin } from './launcher-client.js';
+import { localRemixReference, RemixReferenceToolError, remixReferenceToolRequestSchema } from '../../references/protocol.js';
+const ACTIVE = new Set(['dispatched', 'accepted', 'uncertain']);
+const candidatesSchema = z.object({ items: z.array(z.unknown()).max(50),
+    total: z.number().int().nonnegative(), page: z.number().int().positive(), pageSize: z.number().int().positive() }).strict();
+const SOURCE_ERRORS = new Set(['remix_reference_unavailable', 'remix_reference_too_large', 'remix_reference_incomplete',
+    'remix_reference_unsupported', 'remix_reference_source_changed', 'workspace_access_denied', 'workspace_permission_denied']);
+/** Executes source-reference operations only for the shell and native turn owning this route. */
+export class WorkspaceRemixReferencesBroker {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    operation(context, valid, write = false) {
+        const state = this.state;
+        const session = state.journal.getSession(context.sessionId);
+        const operations = state.journal.listOperations().map(item => item.operation).filter(operation => ['session.turn', 'session.review', 'session.compact'].includes(operation.kind)
+            && ACTIVE.has(operation.status) && operation.generation === state.config.generation && operation.runtimeEpoch === state.runtimeEpoch);
+        const operation = operations.length === 1 ? operations[0] : undefined;
+        if (!valid() || context.refsBlocked || state.journal.destroyed() || !operation || operation.kind !== 'session.turn' || operation.sessionId !== context.sessionId
+            || operation.generation !== state.config.generation || operation.runtimeEpoch !== state.runtimeEpoch
+            || operation.clientRequestId !== context.clientRequestId || !operation.workspaceId || !operation.directoryName
+            || operation.directoryName === 'root' || !operation.nativeThreadId || !operation.nativeTurnId
+            || !session || session.threadId !== operation.nativeThreadId || session.activeTurnId !== operation.nativeTurnId
+            || session.cwd !== context.cwd || session.workspaceId !== operation.workspaceId
+            || (session.directoryName ?? 'basic') !== operation.directoryName || session.turnBlock === 'uncertain'
+            || !['running', 'waiting_for_user'].includes(session.turnStatus ?? ''))
+            throw new RemixReferenceToolError('remix_reference_turn_unavailable');
+        if (write) {
+            if ((operation.leaseFence ?? 0) < state.acceptedLeaseFence)
+                throw new RemixReferenceToolError('remix_reference_turn_unavailable');
+            if (context.readOnly || operation.workMode === 'plan' || operation.permissionMode === 'read-only' || session.permissionMode === 'read-only')
+                throw new RemixReferenceToolError('remix_reference_readonly');
+            if (state.journal.listSessions().some(other => other.sessionId !== context.sessionId
+                && other.workspaceId === operation.workspaceId
+                && ((other.directoryName ?? 'basic') === operation.directoryName || other.directoryName === 'root')
+                && (other.turnBlock === 'uncertain' || ['starting', 'running', 'waiting_for_user'].includes(other.turnStatus ?? ''))))
+                throw new RemixReferenceToolError('turn_already_active');
+        }
+        return operation;
+    }
+    async current(context, valid, write = false) {
+        const operation = this.operation(context, valid, write);
+        const scope = await workspaceContextFromRoot(this.state, context.cwd);
+        if (scope.workspaceId !== operation.workspaceId || scope.directoryName !== operation.directoryName)
+            throw new RemixReferenceToolError('remix_reference_scope_mismatch');
+        if (write && await batchDirectoryHeld(this.state, scope.workspaceId, scope.directoryName))
+            throw new RemixReferenceToolError('batch_workspace_readonly');
+        this.operation(context, valid, write);
+        return { ...scope, operation };
+    }
+    async forward(request, response, context, valid) {
+        const reply = (status, value) => {
+            response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+            response.end(JSON.stringify(value));
+        };
+        try {
+            if (request.socket.remoteAddress !== '127.0.0.1')
+                throw new RemixReferenceToolError('remix_reference_turn_unavailable');
+            let text = '';
+            for await (const chunk of request) {
+                text += chunk.toString();
+                if (Buffer.byteLength(text) > 16 * 1024)
+                    throw new RemixReferenceToolError('invalid_remix_reference_tool_request');
+            }
+            const parsed = remixReferenceToolRequestSchema.safeParse(JSON.parse(text));
+            if (!parsed.success)
+                throw new RemixReferenceToolError('invalid_remix_reference_tool_request');
+            const input = parsed.data;
+            const write = input.action === 'import';
+            const scope = await this.current(context, valid, write);
+            const callerCwd = await realpath(input.cwd);
+            const childPath = relative(context.cwd, callerCwd);
+            if (isAbsolute(childPath) || childPath === '..' || childPath.startsWith('../') || input.workspaceId !== undefined && input.workspaceId !== scope.workspaceId
+                || input.directoryName !== undefined && input.directoryName !== scope.directoryName)
+                throw new RemixReferenceToolError('remix_reference_scope_mismatch');
+            const socketPath = process.env.PLAYCRAFT_LAUNCHER_SOCKET;
+            if (!socketPath || !context.boundaryId || !request.socket.localPort || !request.socket.remotePort
+                || !await verifyLauncherOrigin({ socketPath, boundaryId: context.boundaryId, runtimeEpoch: this.state.runtimeEpoch,
+                    serverPort: request.socket.localPort, clientPort: request.socket.remotePort, cwd: context.originCwd ?? callerCwd }))
+                throw new RemixReferenceToolError('remix_reference_turn_unavailable');
+            await this.current(context, valid, write);
+            if (input.action === 'list') {
+                const items = await this.state.journal.exclusive(`workspace:${scope.workspaceId}:${scope.directoryName}`, () => listWorkspaceRemixReferences(context.cwd, scope.directoryName));
+                this.operation(context, valid);
+                return reply(200, { ok: true, workspaceId: scope.workspaceId, directoryName: scope.directoryName,
+                    items: items.map(reference => localRemixReference(context.cwd, reference)) });
+            }
+            if (input.action === 'search') {
+                const result = candidatesSchema.parse(await this.upstream(scope, { action: 'search', source: input.source,
+                    ...(input.tagCategory === undefined ? {} : { tagCategory: input.tagCategory, tagValues: input.tagValues }),
+                    ...(input.q === undefined ? {} : { q: input.q }), page: input.page, limit: input.limit }, 2 * 1024 * 1024));
+                await this.current(context, valid);
+                return reply(200, { ok: true, workspaceId: scope.workspaceId, directoryName: scope.directoryName, ...result,
+                    items: result.items.map(item => workspaceRemixReferenceCandidateSchema.parse(item)) });
+            }
+            const result = await withDirectoryWrite(this.state, { workspaceId: scope.workspaceId, directoryName: scope.directoryName,
+                sessionId: context.sessionId, wait: false }, async () => {
+                await this.current(context, valid, true);
+                const raw = await this.upstream(scope, { action: 'export', projectUuid: input.projectUuid, branchName: input.branchName }, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES);
+                await this.current(context, valid, true);
+                const snapshot = workspaceRemixReferenceExportSchema.parse(raw);
+                if (snapshot.source.environment !== this.state.config.environment || snapshot.source.projectUuid !== input.projectUuid
+                    || snapshot.source.branchName !== input.branchName)
+                    throw new RemixReferenceToolError('remix_reference_unavailable');
+                return this.state.journal.exclusive(`workspace:${scope.workspaceId}:${scope.directoryName}`, async () => {
+                    await this.current(context, valid, true);
+                    await shareWorkspaceGit(this.state, context.cwd);
+                    await this.current(context, valid, true);
+                    const reference = await importWorkspaceRemixReference(context.cwd, scope.directoryName, snapshot, () => {
+                        this.operation(context, valid, true);
+                    });
+                    this.operation(context, valid, true);
+                    await this.state.journal.allocateSourceEvent({ runtimeId: this.state.config.runtimeId,
+                        generation: this.state.config.generation, runtimeEpoch: this.state.runtimeEpoch,
+                        type: 'workspace.references.imported', occurredAt: new Date().toISOString(),
+                        sessionId: context.sessionId, workspaceId: scope.workspaceId, operationId: scope.operation.operationId,
+                        payload: { sessionId: context.sessionId, workspaceId: scope.workspaceId, directoryName: scope.directoryName,
+                            referenceId: reference.referenceId, path: reference.path, contentHash: reference.contentHash } });
+                    await this.state.journal.allocateSourceEvent({ runtimeId: this.state.config.runtimeId,
+                        generation: this.state.config.generation, runtimeEpoch: this.state.runtimeEpoch,
+                        type: 'files.changed', occurredAt: new Date().toISOString(), sessionId: context.sessionId,
+                        workspaceId: scope.workspaceId, operationId: scope.operation.operationId,
+                        payload: { workspaceId: scope.workspaceId, directoryName: scope.directoryName,
+                            paths: [reference.path, WORKSPACE_REMIX_REFERENCES_MANIFEST], source: 'workspace.references.import',
+                            operationId: scope.operation.operationId } });
+                    wakeSourceEventUploader(this.state);
+                    return reference;
+                });
+            });
+            return reply(200, { ok: true, workspaceId: scope.workspaceId, directoryName: scope.directoryName,
+                reference: localRemixReference(context.cwd, result) });
+        }
+        catch (error) {
+            if (response.headersSent) {
+                response.destroy();
+                return;
+            }
+            const code = error instanceof SyntaxError ? 'invalid_remix_reference_tool_request' : error instanceof RemixReferenceToolError ? error.code
+                : error instanceof Error && /^(?:remix_reference_[a-z_]+|directory_busy)$/.test(error.message)
+                    ? error.message : 'remix_reference_tool_failed';
+            reply(code === 'invalid_remix_reference_tool_request' ? 400
+                : ['turn_already_active', 'batch_workspace_readonly', 'directory_busy'].includes(code) ? 409 : 403, { ok: false, error: { code } });
+        }
+    }
+    async upstream(scope, input, limit) {
+        const config = this.state.config;
+        const response = await fetch(platformEndpoint(config.publicBaseUrl, PLATFORM_ROUTES.remixReferenceTools), {
+            method: 'POST', redirect: 'error', signal: AbortSignal.timeout(120_000),
+            headers: { authorization: `Bearer ${config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': config.environment },
+            body: JSON.stringify({ runtimeId: config.runtimeId, generation: config.generation, runtimeEpoch: this.state.runtimeEpoch,
+                workspaceId: scope.workspaceId, directoryName: scope.directoryName, ...input }),
+        });
+        const chunks = [];
+        let bytes = 0;
+        if (!response.body)
+            throw new RemixReferenceToolError('remix_reference_unavailable');
+        for await (const chunk of response.body) {
+            bytes += chunk.byteLength;
+            if (bytes > (response.ok ? limit : 8192)) {
+                await response.body.cancel().catch(() => undefined);
+                throw new RemixReferenceToolError('remix_reference_too_large');
+            }
+            chunks.push(Buffer.from(chunk));
+        }
+        const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (!response.ok) {
+            const code = [value?.reason, value?.code, value?.message, value?.error?.reason, value?.error?.code]
+                .find(code => typeof code === 'string' && SOURCE_ERRORS.has(code));
+            throw new RemixReferenceToolError(code ?? 'remix_reference_unavailable');
+        }
+        return value;
+    }
+}

package/dist/workspace-runtime/codex/scheduled-task-tools.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { scheduledTaskProposalDraftSchema, scheduledTaskProposalDraftJsonSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { rejectTool, toolContent } from './tool-response.js';
+export const WORKSPACE_SCHEDULED_TASK_TOOLS = [
+    { type: 'function', name: 'playcraft_get_scheduled_task_context',
+        description: 'Read server time, scheduling defaults, and tasks actually related to this conversation. The returned timeZone describes the server clock, not the user’s local timezone; clarify the intended timezone when it is unknown. When several tasks match, ask the user which task to change. This tool never changes a task.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    { type: 'function', name: 'playcraft_propose_scheduled_task',
+        description: 'Prepare a scheduled-task creation or change for the user to review in a persistent confirmation card. Read scheduling context first. This does not create or change a task: only the user can confirm the card. A pending_confirmation result must never be reported as an applied task.',
+        inputSchema: { type: 'object', properties: {
+                draft: scheduledTaskProposalDraftJsonSchema, supersedesProposalId: { type: 'string', format: 'uuid' },
+            }, required: ['draft'], additionalProperties: false } },
+];
+export const SCHEDULED_TASK_TOOL_ERROR_CODES = new Set([
+    'unavailable', 'source_unavailable', 'source_pending', 'invalid_input', 'request_conflict', 'request_pending',
+    'feature_disabled', 'limit', 'version_conflict', 'schedule_expired', 'invalid_time_zone', 'interval_too_short',
+    'target_read_only', 'target_unavailable', 'target_access_denied', 'target_binding_changed', 'session_unavailable',
+    'account_unavailable', 'model_unavailable', 'reasoning_effort_unavailable', 'revoked',
+].map(code => `scheduled_task_proposal_${code}`));
+const prepareArguments = z.object({ draft: z.unknown(), supersedesProposalId: z.string().uuid().optional() }).strict();
+const sourceKey = (source) => JSON.stringify([source.threadId, source.turnId, source.toolCallId]);
+/** Only a live root-native call can attest the source of a prepare-only bridge request. */
+export class WorkspaceScheduledTaskTools {
+    handler;
+    changed;
+    active = new Map();
+    settled = new Map();
+    constructor(handler, changed) {
+        this.handler = handler;
+        this.changed = changed;
+    }
+    isActive(source) {
+        const call = this.active.get(sourceKey(source));
+        return Boolean(call && call.source.bridge === source.bridge && call.current());
+    }
+    async request(requestId, payload, client, context) {
+        if (!context?.bridge || !context.current() || typeof payload.callId !== 'string' || !payload.callId.length
+            || payload.namespace)
+            return rejectTool(client, requestId, 'scheduled_task_proposal_source_unavailable');
+        const action = payload.tool === 'playcraft_get_scheduled_task_context' ? 'context'
+            : payload.tool === 'playcraft_propose_scheduled_task' ? 'prepare' : undefined;
+        const parsed = action === 'context' ? z.object({}).strict().safeParse(payload.arguments)
+            : prepareArguments.safeParse(payload.arguments);
+        if (!action || !parsed.success || (action === 'prepare'
+            && !scheduledTaskProposalDraftSchema.safeParse(parsed.data.draft).success))
+            return rejectTool(client, requestId, 'scheduled_task_proposal_invalid_input');
+        const source = { bridge: context.bridge, threadId: context.threadId, turnId: context.turnId, toolCallId: payload.callId };
+        const key = sourceKey(source), fingerprint = JSON.stringify([action, parsed.data]);
+        const prior = this.settled.get(key);
+        if (prior) {
+            if (prior.fingerprint !== fingerprint)
+                return rejectTool(client, requestId, 'scheduled_task_proposal_request_conflict');
+            await client.respond(requestId, { success: true, contentItems: toolContent(prior.result) });
+            return;
+        }
+        if (this.active.has(key))
+            return rejectTool(client, requestId, 'scheduled_task_proposal_request_pending');
+        this.active.set(key, { source, current: context.current });
+        try {
+            const result = await this.handler(action, source, parsed.data);
+            this.settled.set(key, { fingerprint, result });
+            if (this.settled.size > 256)
+                this.settled.delete(this.settled.keys().next().value);
+            if (action === 'prepare' && result && typeof result === 'object'
+                && 'proposalId' in result && typeof result.proposalId === 'string')
+                this.changed(result.proposalId, source);
+            await client.respond(requestId, { success: true, contentItems: toolContent(result) });
+        }
+        catch (error) {
+            await rejectTool(client, requestId, error instanceof Error && SCHEDULED_TASK_TOOL_ERROR_CODES.has(error.message)
+                ? error.message : 'scheduled_task_proposal_unavailable');
+        }
+        finally {
+            this.active.delete(key);
+        }
+    }
+}
+export function isWorkspaceScheduledTaskTool(value) {
+    return WORKSPACE_SCHEDULED_TASK_TOOLS.some(tool => tool.name === value);
+}

package/dist/workspace-runtime/serve.js

@@ -33,6 +33,7 @@ import { observeWorkspaceArtifacts } from './workspaces/artifact-events.js';
 import { loadWorkspaceMcpConfig } from './codex/mcp-config.js';
 import { startSourceEventUploader, stopSourceEventUploader } from './server/source-uploader.js';
 import { platformExportTarget, readPlatformExport, startPlatformExport } from './workspaces/platform-export.js';
+import { scheduledTaskProposalHandler } from './workspaces/scheduled-task-proposals.js';
 export async function startWorkspaceRuntime(config, options = {}) {
     process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
     const negotiated = negotiateProtocol(config);
@@ -412,6 +413,7 @@ function defaultNativeAdapter(state) {
             config,
             workspaceUi: true,
             deliveryTools: deliveryToolHandlers(state),
+            scheduledTaskProposals: scheduledTaskProposalHandler(state),
             ...(multi ? { modelBroker: new WorkspaceModelBroker(state) } : {}),
             ...(multi ? { loadMcpConfig: async (cwd) => {
                     const { workspaceId } = await workspaceContextFromRoot(state, cwd);

package/dist/workspace-runtime/server/dispatch.js

@@ -497,6 +497,7 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
             workMode: selection.data.workMode ?? 'execute',
             skillsLockHash: composer.skillsLockHash,
             uiSnapshot: uiSnapshot.data,
+            scheduledTaskProposalBridge: typeof body.scheduledTaskProposalBridge === 'string' ? body.scheduledTaskProposalBridge : undefined,
             simulateLostReceipt: body.simulateLostReceipt === true,
             persistReservation: async ({ nativeRequestId, modelConfigId, reasoningEffort, permissionMode }) => {
                 const selectedEffort = reasoningEffort ?? requestedEffort;

package/dist/workspace-runtime/server/http.js

@@ -134,6 +134,7 @@ async function dispatchRuntimeRequest(state, request, response) {
                 composerContextVersion: 1,
                 scheduledTaskIdentityVersion: 1,
                 scheduledTaskCancellationVersion: 1,
+                ...(state.native?.scheduledTaskProposalSource ? { scheduledTaskProposalVersion: 1 } : {}),
                 parameterAgentVersion: 1,
                 directoryConcurrencyVersion: 1,
                 parameterInitializationVersion: 1,
@@ -812,6 +813,16 @@ async function dispatchRuntimeRequest(state, request, response) {
             writeJson(response, 200, operation);
             return;
         }
+        if (request.method === 'POST' && url.pathname === '/runtime/scheduled-task-proposals/source') {
+            const body = await readJson(request);
+            if (!body || Object.keys(body).some(key => !['bridge', 'threadId', 'turnId', 'toolCallId'].includes(key))
+                || !['bridge', 'threadId', 'turnId', 'toolCallId'].every(key => typeof body[key] === 'string' && Boolean(body[key]))) {
+                writeJson(response, 400, { valid: false });
+                return;
+            }
+            writeJson(response, 200, { valid: state.native?.scheduledTaskProposalSource?.(body) === true });
+            return;
+        }
         if (request.method === 'POST' && url.pathname === '/runtime/operations') {
             // Track creation before accepting it, so a new unconnected terminal is known not to have spawned.
             terminalHost(state);
@@ -977,7 +988,9 @@ async function acceptOperation(state, request, response) {
         ? { snapshot: parsed.data.remixReferenceSnapshot }
         : parsed.data.kind === 'asset.library.import'
             ? { selection: parsed.data.payload, snapshot: parsed.data.libraryAssetImports }
-            : parsed.data.payload;
+            : parsed.data.kind === 'session.turn' && parsed.data.scheduledTaskProposalBridge
+                ? { ...asRecord(parsed.data.payload), scheduledTaskProposalBridge: parsed.data.scheduledTaskProposalBridge }
+                : parsed.data.payload;
     const accept = async () => {
         const result = await acceptOperationCore(state, parsed.data, {
             leaseFence: incomingFence,

package/dist/workspace-runtime/workspaces/empty-template.js

@@ -6,12 +6,14 @@ import { createHash } from 'node:crypto';
 import { canonicalProjectSkillsJson } from '@playcraft/common/project-skills';
 import { syncLocalProjectSkills } from '../../project-skills/local-store.js';
 import { selectOptionalPlatformSkills } from './optional-platform-skills.js';
+import { WORKSPACE_REMIX_REFERENCES_SKILL } from './remix-reference-skill.js';
 export const EMPTY_WORKSPACE_REPOSITORY_SKILLS = [
     'playcraft-skill-recommender',
     'playcraft-image-generation',
     'playcraft-audio-generation',
     'playcraft-image-processing',
     'playcraft-workspace-assets',
+    WORKSPACE_REMIX_REFERENCES_SKILL,
     'playcraft-build-optimizer',
 ];
 export const EMPTY_WORKSPACE_PLATFORM_SKILLS = ['playcraft-video-understanding', 'playcraft-replica-validation'];