@playcraft/cli 0.1.70 → 0.1.72

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

@@ -1,14 +1,15 @@
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
-import { Readable } from 'node:stream';
+import { Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { basename, dirname } from 'node:path';
 import { z } from 'zod';
 import { workspaceContextFromRoot } from '../workspaces/registry.js';
-import { PLATFORM_ROUTES, modelResponsesPath, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
+import { PLATFORM_ROUTES, modelResponsesPath, platformEndpoint, workspaceExecutionTraceOriginSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { WorkspaceGenerationProvenanceBroker } from './generation-provenance-broker.js';
 import { WorkspaceRemixReferencesBroker } from './remix-references-broker.js';
 import { WorkspaceExecutionContextBroker } from './execution-context-broker.js';
+import { WorkspaceSkillDiscoveryBroker } from './skill-discovery-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),
@@ -16,6 +17,7 @@ const credentialSchema = z.object({
     claims: z.object({
         environment: z.string(), userId: z.string(), workspaceId: z.string(), runtimeId: z.string(),
         generation: z.number().int(), runtimeEpoch: z.number().int(),
+        traceOrigin: z.custom(value => workspaceExecutionTraceOriginSchema.safeParse(value).success).optional(),
     }),
 });
 const MAX_MODEL_REQUEST_BYTES = 128 * 1024 * 1024;
@@ -32,11 +34,13 @@ export class WorkspaceModelBroker {
     generation;
     references;
     executionContext;
+    skills;
     constructor(state) {
         this.state = state;
         this.generation = new WorkspaceGenerationProvenanceBroker(state);
         this.references = new WorkspaceRemixReferencesBroker(state);
         this.executionContext = new WorkspaceExecutionContextBroker(state);
+        this.skills = new WorkspaceSkillDiscoveryBroker(state);
     }
     async start() {
         if (this.server)
@@ -81,7 +85,8 @@ 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'), referencesCapability: randomBytes(32).toString('base64url') };
+                generationCapability: randomBytes(32).toString('base64url'), referencesCapability: randomBytes(32).toString('base64url'),
+                skillsCapability: randomBytes(32).toString('base64url') };
             this.routes.set(routeKey, route);
         }
         // Each session pins its prepared model; shared credential renewal cannot change an active turn.
@@ -123,6 +128,8 @@ export class WorkspaceModelBroker {
                         PLAYCRAFT_AGENT_GENERATION_CAPABILITY: route.generationCapability,
                         PLAYCRAFT_REMIX_REFERENCES_ENDPOINT: `${this.baseUrl}/${routeKey}/remix-references`,
                         PLAYCRAFT_REMIX_REFERENCES_CAPABILITY: route.referencesCapability,
+                        PLAYCRAFT_SKILLS_ENDPOINT: `${this.baseUrl}/${routeKey}/skill-discovery`,
+                        PLAYCRAFT_SKILLS_CAPABILITY: route.skillsCapability,
                     } } : {}),
                 'model_providers.playcraft_workspace': {
                     name: 'PlayCraft Workspace', base_url: `${this.baseUrl}/${routeKey}`,
@@ -137,6 +144,16 @@ export class WorkspaceModelBroker {
             && this.state.runtimeEpoch === entry.epoch && this.state.journal.getWorkspace(entry.workspaceId)
             && this.entries.get(entry.cacheKey) === entry);
     }
+    /** Called immediately before the native turn/start write, within this broker's process clock. */
+    markCodexDispatched(cwd, sessionId, clientRequestId) {
+        const workspaceId = /^(basic|remix-)/.test(basename(cwd)) ? basename(dirname(cwd)) : basename(cwd);
+        const route = this.routes.get(`${workspaceId}/${createHash('sha256').update(sessionId).digest('hex').slice(0, 32)}`);
+        const entry = route?.selected?.entry;
+        if (!entry || !this.valid(entry) || entry.sessionId !== sessionId || entry.clientRequestId !== clientRequestId)
+            return;
+        entry.codexDispatchedAt = new Date().toISOString();
+        entry.codexDispatchMark = performance.now();
+    }
     async credential(entry, refresh = false) {
         if (!this.valid(entry))
             throw new Error('model_access_denied');
@@ -179,13 +196,16 @@ export class WorkspaceModelBroker {
         return credential;
     }
     async forward(request, response) {
+        const receivedMark = performance.now();
+        const receivedAt = new Date().toISOString();
+        const elapsed = (start) => Math.max(0, Math.round(performance.now() - start));
         const abort = new AbortController();
         this.requests.add(abort);
         let activeRoute;
         const cancel = () => abort.abort();
         response.once('close', cancel);
         try {
-            const match = /^\/([0-9a-f-]{36}(?:\/[0-9a-f]{32})?)\/(responses|generation-provenance|remix-references|execution-context)$/.exec(request.url ?? '');
+            const match = /^\/([0-9a-f-]{36}(?:\/[0-9a-f]{32})?)\/(responses|generation-provenance|remix-references|execution-context|skill-discovery\/(?:match|selection|artifact|activate))$/.exec(request.url ?? '');
             const route = match ? this.routes.get(match[1]) : undefined;
             const selected = route?.selected;
             const entry = selected?.entry;
@@ -193,8 +213,9 @@ export class WorkspaceModelBroker {
             const generationRequest = match?.[2] === 'generation-provenance';
             const contextRequest = match?.[2] === 'execution-context';
             const referencesRequest = match?.[2] === 'remix-references';
+            const skillsRequest = match?.[2]?.startsWith('skill-discovery/');
             const expected = Buffer.from(route ? `Bearer ${generationRequest || contextRequest ? route.generationCapability
-                : referencesRequest ? route.referencesCapability : route.capability}` : '');
+                : referencesRequest ? route.referencesCapability : skillsRequest ? route.skillsCapability : route.capability}` : '');
             if (request.method !== 'POST' || !entry || !expected.length || presented.length !== expected.length
                 || !timingSafeEqual(presented, expected) || !this.valid(entry)) {
                 response.writeHead(403);
@@ -228,6 +249,16 @@ export class WorkspaceModelBroker {
                 await this.references.forward(request, response, selected.feedback, () => this.valid(entry) && route?.selected === selected);
                 return;
             }
+            if (skillsRequest) {
+                if (!selected?.feedback) {
+                    response.writeHead(403);
+                    response.end();
+                    return;
+                }
+                const action = match[2].slice('skill-discovery/'.length);
+                await this.skills.forward(request, response, selected.feedback, () => this.valid(entry) && route?.selected === selected, action);
+                return;
+            }
             const rejectOversizedBody = () => {
                 response.writeHead(413, { 'content-type': 'application/json', 'cache-control': 'no-store' });
                 response.end(JSON.stringify({ error: { message: 'model_request_too_large',
@@ -242,7 +273,10 @@ export class WorkspaceModelBroker {
             const active = this.sessionRequests.get(route) ?? new Set();
             active.add(abort);
             this.sessionRequests.set(route, active);
+            const credentialMark = performance.now();
             const credential = await this.credential(entry);
+            const credentialWaitMs = elapsed(credentialMark);
+            const requestReadMark = performance.now();
             const chunks = [];
             let size = 0;
             for await (const chunk of request) {
@@ -253,6 +287,7 @@ export class WorkspaceModelBroker {
                 }
                 chunks.push(Buffer.from(chunk));
             }
+            const requestReadMs = elapsed(requestReadMark);
             if (!this.valid(entry))
                 throw new Error('model_access_denied');
             const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
@@ -280,16 +315,37 @@ export class WorkspaceModelBroker {
                 };
             }
             const expires = setTimeout(cancel, Math.max(0, Date.parse(credential.expiresAt) - Date.now()));
+            const dispatchedAt = new Date().toISOString();
+            const dispatchedMark = performance.now();
+            const beforeDispatchMs = elapsed(receivedMark);
+            const candidateOrigin = credential.claims.traceOrigin;
+            const origin = candidateOrigin?.sessionId === entry.sessionId && candidateOrigin?.clientRequestId === entry.clientRequestId
+                ? candidateOrigin : undefined;
+            const broker = { receivedAt, dispatchedAt,
+                credentialWaitMs, requestReadMs, beforeDispatchMs };
+            let attemptId;
+            let outcome = 'error';
             try {
                 const upstream = await fetch(platformEndpoint(this.state.config.publicBaseUrl, modelResponsesPath(credential.configId)), {
                     method: 'POST', redirect: 'error', signal: abort.signal,
                     headers: { authorization: `Bearer ${credential.token}`, 'content-type': 'application/json',
+                        ...(origin ? { 'x-playcraft-model-journey': JSON.stringify({ version: 1,
+                                runtimeOperationId: origin.runtimeOperationId, sessionId: origin.sessionId, clientRequestId: origin.clientRequestId,
+                                ...(entry.codexDispatchedAt ? { codexDispatchedAt: entry.codexDispatchedAt } : {}),
+                                brokerReceivedAt: receivedAt, brokerDispatchedAt: dispatchedAt, credentialWaitMs, requestReadMs, beforeDispatchMs,
+                                ...(entry.codexDispatchMark === undefined ? {} : { codexDispatchToBrokerMs: Math.max(0, Math.round(receivedMark - entry.codexDispatchMark)) }),
+                            }) } : {}),
                         ...(selected?.feedback ? {
                             'x-playcraft-cloud-session-id': selected.feedback.sessionId,
                             'x-playcraft-client-request-id': selected.feedback.clientRequestId,
                         } : {}) },
                     body: JSON.stringify(body),
                 });
+                broker.responseHeadersAt = new Date().toISOString();
+                broker.proxyResponseHeadersMs = elapsed(dispatchedMark);
+                const reference = upstream.headers.get('x-model-attempt-id');
+                if (reference && z.string().uuid().safeParse(reference).success)
+                    attemptId = reference;
                 if (upstream.status === 401 || upstream.status === 403)
                     entry.credential = undefined;
                 const admissionReason = upstream.headers.get('x-model-admission-reason')?.trim();
@@ -305,12 +361,33 @@ export class WorkspaceModelBroker {
                     ...(retryAfter ? { 'retry-after': retryAfter } : {}),
                 });
                 if (upstream.body)
-                    await pipeline(Readable.fromWeb(upstream.body), response);
+                    await pipeline(Readable.fromWeb(upstream.body), new Transform({
+                        transform(chunk, _encoding, callback) {
+                            if (chunk.length && broker.firstBodyByteAt === undefined) {
+                                broker.firstBodyByteAt = new Date().toISOString();
+                                broker.proxyFirstBodyByteMs = elapsed(dispatchedMark);
+                            }
+                            callback(null, chunk);
+                        },
+                    }), response);
                 else
                     response.end();
+                outcome = 'completed';
+            }
+            catch (error) {
+                outcome = abort.signal.aborted ? 'interrupted' : 'error';
+                throw error;
             }
             finally {
                 clearTimeout(expires);
+                broker.completedAt = new Date().toISOString();
+                broker.proxyResponseDurationMs = elapsed(dispatchedMark);
+                if (origin && attemptId) {
+                    // Telemetry is sent after transfer and cannot delay or change the Codex model response.
+                    void this.reportObservation(credential.token, { version: 1, attemptId,
+                        runtimeOperationId: origin.runtimeOperationId, sessionId: origin.sessionId,
+                        clientRequestId: origin.clientRequestId, broker, outcome });
+                }
             }
         }
         catch {
@@ -332,6 +409,16 @@ export class WorkspaceModelBroker {
             }
         }
     }
+    async reportObservation(token, input) {
+        try {
+            const response = await fetch(platformEndpoint(this.state.config.publicBaseUrl, '/api/llm-proxy/runtime-observations'), {
+                method: 'POST', redirect: 'error', signal: AbortSignal.timeout(3_000),
+                headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, body: JSON.stringify(input),
+            });
+            await response.body?.cancel();
+        }
+        catch { /* Missing observations remain unknown; never replay a model request for telemetry. */ }
+    }
     cancelSession(cwd, sessionId) {
         const routeKey = `${/^(basic|remix-)/.test(basename(cwd)) ? basename(dirname(cwd)) : basename(cwd)}/${createHash('sha256').update(sessionId).digest('hex').slice(0, 32)}`;
         const route = this.routes.get(routeKey);

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

@@ -5,16 +5,30 @@ import { PLATFORM_ROUTES, platformEndpoint, WORKSPACE_REMIX_REFERENCE_BODY_MAX_B
 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 { importWorkspaceRemixReference, listWorkspaceRemixReferences, } from '../workspaces/remix-references.js';
 import { shareWorkspaceGit } from '../workspaces/shared-git.js';
+import { prepareStarterTemplate } from '../workspaces/starter-template.js';
 import { batchDirectoryHeld } from '../batch/occupancy.js';
 import { verifyLauncherOrigin } from './launcher-client.js';
-import { localRemixReference, RemixReferenceToolError, remixReferenceToolRequestSchema } from '../../references/protocol.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']);
+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;
@@ -24,27 +38,53 @@ export class WorkspaceRemixReferencesBroker {
     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 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 ?? ''))
+        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')
+            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 ?? ''))))
+            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;
@@ -52,16 +92,20 @@ export class WorkspaceRemixReferencesBroker {
     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)
+        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))
+        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.writeHead(status, {
+                'content-type': 'application/json',
+                'cache-control': 'no-store',
+            });
             response.end(JSON.stringify(value));
         };
         try {
@@ -77,41 +121,87 @@ export class WorkspaceRemixReferencesBroker {
             if (!parsed.success)
                 throw new RemixReferenceToolError('invalid_remix_reference_tool_request');
             const input = parsed.data;
-            const write = input.action === 'import';
+            const write = input.action === 'import' || input.action === 'prepare-starter-template';
             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)
+            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 }))
+            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)) });
+                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));
+                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)) });
+                return reply(200, {
+                    ok: true,
+                    workspaceId: scope.workspaceId,
+                    directoryName: scope.directoryName,
+                    ...result,
+                    items: result.items.map((item) => workspaceRemixReferenceCandidateSchema.parse(item)),
+                });
+            }
+            if (input.action === 'prepare-starter-template') {
+                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: 'starter-template' }, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES);
+                    await this.current(context, valid, true);
+                    return prepareStarterTemplate(context.cwd, raw, () => this.operation(context, valid, true));
+                });
+                return reply(200, { ok: true, workspaceId: scope.workspaceId, directoryName: scope.directoryName, ...result });
             }
-            const result = await withDirectoryWrite(this.state, { workspaceId: scope.workspaceId, directoryName: scope.directoryName,
-                sessionId: context.sessionId, wait: false }, async () => {
+            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)
+                if (snapshot.source.environment !== this.state.config.environment ||
+                    !('projectUuid' in snapshot.source) ||
+                    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);
@@ -121,45 +211,91 @@ export class WorkspaceRemixReferencesBroker {
                         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 } });
+                    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) });
+            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 } });
+            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 }),
+            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;
@@ -175,8 +311,13 @@ export class WorkspaceRemixReferencesBroker {
         }
         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));
+            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;