@elizaos/shared 2.0.0-beta.1 → 2.0.3-beta.3

package/contracts/app-permissions.js

@@ -0,0 +1,163 @@
+/**
+ * Parser and types for the `elizaos.app.permissions` manifest block declared
+ * by third-party apps in their `package.json`. Spec lives at
+ * `eliza/packages/docs/architecture/app-permissions-manifest.md` and is the
+ * source of truth — this module implements the validation rules described
+ * there. The manifest is advisory in this slice (no enforcement).
+ *
+ * Forward compatibility: only the recognised namespaces (`fs`, `net`) are
+ * validated and surfaced as typed slices. Unrecognised keys inside the
+ * `permissions` object are preserved verbatim under `raw` so a later
+ * Eliza version that recognises them can read them out of the persisted
+ * registry without re-parsing the source manifest.
+ *
+ * NOTE: this module is distinct from `./permissions.ts`, which describes
+ * OS-level system permissions (camera, microphone, accessibility). App
+ * permissions are an in-runtime sandbox concept declared by an app's
+ * package.json; system permissions are an OS concept granted to the
+ * Eliza binary itself.
+ */
+export const MAX_PATTERN_LENGTH = 256;
+/**
+ * Namespaces this Eliza version recognises in `elizaos.app.permissions`.
+ * The parser surfaces only these as typed slices; other namespace keys
+ * declared by an app are preserved verbatim under `raw` for forward
+ * compatibility but cannot be granted (a later Eliza version that
+ * recognises them adds them here).
+ *
+ * Source of truth for the granted-permission store's namespace
+ * intersection — see
+ * `eliza/packages/docs/architecture/app-permissions-granted-store.md`.
+ */
+export const RECOGNISED_PERMISSION_NAMESPACES = ["fs", "net"];
+/**
+ * Returns the recognised namespaces actually declared by a parsed
+ * manifest. This is what a consent UI should render as toggleable rows.
+ */
+export function recognisedNamespacesFor(manifest) {
+    const out = [];
+    if (manifest.fs !== undefined)
+        out.push("fs");
+    if (manifest.net !== undefined)
+        out.push("net");
+    return out;
+}
+/**
+ * Returns the recognised namespaces actually declared by a raw
+ * `requestedPermissions` object as persisted on `AppRegistryEntry`.
+ * Equivalent to `recognisedNamespacesFor(parseAppPermissions(raw))`
+ * when the raw shape is well-formed, but tolerant of malformed
+ * persisted state (returns `[]` rather than throwing).
+ */
+export function recognisedNamespacesForRaw(raw) {
+    if (!raw)
+        return [];
+    const result = parseAppPermissions(raw);
+    if (result.ok === false)
+        return [];
+    return recognisedNamespacesFor(result.manifest);
+}
+/**
+ * Parses a raw `isolation` field from `elizaos.app.isolation` into the
+ * typed enum, defaulting to `"none"` when absent. Unknown values
+ * (including modes a later Eliza version might add) are
+ * coerced to `"none"` to keep the parser forward-compatible.
+ */
+export function parseAppIsolation(value) {
+    if (value === "worker")
+        return "worker";
+    return "none";
+}
+export function parseAppPermissions(value) {
+    if (value === undefined || value === null) {
+        return { ok: true, manifest: { raw: null } };
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return {
+            ok: false,
+            reason: "permissions must be an object",
+            path: "permissions",
+        };
+    }
+    const raw = value;
+    const manifest = { raw };
+    if ("fs" in raw) {
+        const fsResult = parseFs(raw.fs, "permissions.fs");
+        if (fsResult.ok === false)
+            return fsResult;
+        if (fsResult.value !== null)
+            manifest.fs = fsResult.value;
+    }
+    if ("net" in raw) {
+        const netResult = parseNet(raw.net, "permissions.net");
+        if (netResult.ok === false)
+            return netResult;
+        if (netResult.value !== null)
+            manifest.net = netResult.value;
+    }
+    return { ok: true, manifest };
+}
+function parseFs(value, basePath) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, reason: "fs must be an object", path: basePath };
+    }
+    const obj = value;
+    const out = {};
+    if ("read" in obj) {
+        const readResult = parseStringArray(obj.read, `${basePath}.read`, "fs.read must be an array of glob strings");
+        if (readResult.ok === false)
+            return readResult;
+        if (readResult.value !== null)
+            out.read = readResult.value;
+    }
+    if ("write" in obj) {
+        const writeResult = parseStringArray(obj.write, `${basePath}.write`, "fs.write must be an array of glob strings");
+        if (writeResult.ok === false)
+            return writeResult;
+        if (writeResult.value !== null)
+            out.write = writeResult.value;
+    }
+    return { ok: true, value: hasOwnKeys(out) ? out : null };
+}
+function parseNet(value, basePath) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, reason: "net must be an object", path: basePath };
+    }
+    const obj = value;
+    const out = {};
+    if ("outbound" in obj) {
+        const outboundResult = parseStringArray(obj.outbound, `${basePath}.outbound`, "net.outbound must be an array of host pattern strings");
+        if (outboundResult.ok === false)
+            return outboundResult;
+        if (outboundResult.value !== null)
+            out.outbound = outboundResult.value;
+    }
+    return { ok: true, value: hasOwnKeys(out) ? out : null };
+}
+function parseStringArray(value, basePath, shapeError) {
+    if (value === undefined)
+        return { ok: true, value: null };
+    if (!Array.isArray(value)) {
+        return { ok: false, reason: shapeError, path: basePath };
+    }
+    for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        if (typeof item !== "string") {
+            return { ok: false, reason: shapeError, path: `${basePath}[${i}]` };
+        }
+        if (item.length > MAX_PATTERN_LENGTH) {
+            return {
+                ok: false,
+                reason: `${basePath}[${i}] exceeds ${MAX_PATTERN_LENGTH} characters`,
+                path: `${basePath}[${i}]`,
+            };
+        }
+    }
+    return { ok: true, value: value };
+}
+function hasOwnKeys(obj) {
+    for (const _ in obj)
+        return true;
+    return false;
+}
+//# sourceMappingURL=app-permissions.js.map

package/contracts/app-permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-permissions.js","sourceRoot":"","sources":["../../src/contracts/app-permissions.ts"],"names":[],"mappings":"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"}

package/contracts/apps-favorites-routes.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Zod schemas for the apps-favorites HTTP routes — the per-user
+ * favorited-apps store. Fourth migration in the typed-routes
+ * initiative; same template as the rest.
+ *
+ * Routes covered:
+ *   GET  /api/apps/favorites
+ *     200: { favoriteApps: string[] }            (no body to validate)
+ *   PUT  /api/apps/favorites
+ *     body: { appName: string, isFavorite: boolean }
+ *     200:  { favoriteApps: string[] }
+ *   POST /api/apps/favorites/replace
+ *     body: { favoriteAppNames: string[] }
+ *     200:  { favoriteApps: string[] }
+ *
+ * Server-side, all three routes already pipe their writes through
+ * `sanitizeFavoriteAppNames(...)` — the schema's job is to reject
+ * malformed inputs at the wire boundary; sanitization stays as a
+ * second pass on top of validated data.
+ */
+import z from "zod";
+export declare const PutFavoriteAppRequestSchema: z.ZodPipe<z.ZodPipe<z.ZodObject<{
+    appName: z.ZodString;
+    isFavorite: z.ZodBoolean;
+}, z.core.$strict>, z.ZodTransform<{
+    appName: string;
+    isFavorite: boolean;
+}, {
+    appName: string;
+    isFavorite: boolean;
+}>>, z.ZodObject<{
+    appName: z.ZodString;
+    isFavorite: z.ZodBoolean;
+}, z.core.$strict>>;
+export declare const PostReplaceFavoritesRequestSchema: z.ZodObject<{
+    favoriteAppNames: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const FavoritesResponseSchema: z.ZodObject<{
+    favoriteApps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type PutFavoriteAppRequest = z.infer<typeof PutFavoriteAppRequestSchema>;
+export type PostReplaceFavoritesRequest = z.infer<typeof PostReplaceFavoritesRequestSchema>;
+export type FavoritesResponse = z.infer<typeof FavoritesResponseSchema>;
+//# sourceMappingURL=apps-favorites-routes.d.ts.map

package/contracts/apps-favorites-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps-favorites-routes.d.ts","sourceRoot":"","sources":["../../src/contracts/apps-favorites-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB,eAAO,MAAM,2BAA2B;;;;;;;;;;;;mBAiBrC,CAAC;AAEJ,eAAO,MAAM,iCAAiC;;kBAInC,CAAC;AAEZ,eAAO,MAAM,uBAAuB;;kBAIzB,CAAC;AAEZ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,iCAAiC,CACzC,CAAC;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/contracts/apps-favorites-routes.js

@@ -0,0 +1,48 @@
+/**
+ * Zod schemas for the apps-favorites HTTP routes — the per-user
+ * favorited-apps store. Fourth migration in the typed-routes
+ * initiative; same template as the rest.
+ *
+ * Routes covered:
+ *   GET  /api/apps/favorites
+ *     200: { favoriteApps: string[] }            (no body to validate)
+ *   PUT  /api/apps/favorites
+ *     body: { appName: string, isFavorite: boolean }
+ *     200:  { favoriteApps: string[] }
+ *   POST /api/apps/favorites/replace
+ *     body: { favoriteAppNames: string[] }
+ *     200:  { favoriteApps: string[] }
+ *
+ * Server-side, all three routes already pipe their writes through
+ * `sanitizeFavoriteAppNames(...)` — the schema's job is to reject
+ * malformed inputs at the wire boundary; sanitization stays as a
+ * second pass on top of validated data.
+ */
+import z from "zod";
+export const PutFavoriteAppRequestSchema = z
+    .object({
+    appName: z.string().min(1, "appName is required"),
+    isFavorite: z.boolean(),
+})
+    .strict()
+    .transform((value) => ({
+    appName: value.appName.trim(),
+    isFavorite: value.isFavorite,
+}))
+    .pipe(z
+    .object({
+    appName: z.string().min(1, "appName is required"),
+    isFavorite: z.boolean(),
+})
+    .strict());
+export const PostReplaceFavoritesRequestSchema = z
+    .object({
+    favoriteAppNames: z.array(z.string()),
+})
+    .strict();
+export const FavoritesResponseSchema = z
+    .object({
+    favoriteApps: z.array(z.string()),
+})
+    .strict();
+//# sourceMappingURL=apps-favorites-routes.js.map

package/contracts/apps-favorites-routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps-favorites-routes.js","sourceRoot":"","sources":["../../src/contracts/apps-favorites-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC;KACzC,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,qBAAqB,CAAC;IACjD,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE;CACxB,CAAC;KACD,MAAM,EAAE;KACR,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACrB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE;IAC7B,UAAU,EAAE,KAAK,CAAC,UAAU;CAC7B,CAAC,CAAC;KACF,IAAI,CACH,CAAC;KACE,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,qBAAqB,CAAC;IACjD,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE;CACxB,CAAC;KACD,MAAM,EAAE,CACZ,CAAC;AAEJ,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC;KAC/C,MAAM,CAAC;IACN,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CACtC,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC;KACrC,MAAM,CAAC;IACN,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAClC,CAAC;KACD,MAAM,EAAE,CAAC"}

package/contracts/apps-lifecycle-routes.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Zod schemas for the apps-lifecycle HTTP routes
+ * (launch / install / stop / relaunch / create / overlay-presence /
+ * refresh). Same template as the rest: schema in shared, safeParse on
+ * server, infer types on client.
+ *
+ * Routes covered:
+ *   POST /api/apps/launch            body: { name }                  → AppLaunchResult
+ *   POST /api/apps/install           body: { name, version? }        → InstallAppResponse
+ *   POST /api/apps/stop              body: { name?, runId? }         → AppStopResult
+ *                                     (at least one of name/runId required)
+ *   POST /api/apps/relaunch          body: { name, runId?, verify? } → AppLaunchResult
+ *   POST /api/apps/create            body: { intent, editTarget? }   → CreateAppResponse
+ *   POST /api/apps/overlay-presence  body: { appName?: string|null } → OverlayPresenceResponse
+ *   POST /api/apps/refresh           (no body)                       → RefreshAppsResponse
+ *
+ * Response shapes for the routes that delegate to AppLaunchResult or
+ * AppStopResult (launch, stop, relaunch) are still defined by the
+ * TypeScript interfaces in `./apps.ts` — those tree types have not
+ * been migrated to zod yet and are out of scope for this module.
+ */
+import z from "zod";
+export declare const PostLaunchAppRequestSchema: z.ZodPipe<z.ZodPipe<z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strict>, z.ZodTransform<{
+    name: string;
+}, {
+    name: string;
+}>>, z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strict>>;
+export declare const PostInstallAppRequestSchema: z.ZodPipe<z.ZodPipe<z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodTransform<{
+    version?: string | undefined;
+    name: string;
+}, {
+    name: string;
+    version?: string | undefined;
+}>>, z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+/**
+ * /stop accepts `{ name }`, `{ runId }`, or both — but at least one
+ * must be a non-empty string. The `.refine()` does the cross-field
+ * check the route used to do by hand.
+ */
+export declare const PostStopAppRequestSchema: z.ZodPipe<z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodTransform<{
+    runId?: string | undefined;
+    name?: string | undefined;
+}, {
+    name?: string | undefined;
+    runId?: string | undefined;
+}>>;
+/**
+ * /relaunch accepts the launch fields plus optional `runId` (used to
+ * stop a specific run before relaunching, instead of the broader
+ * "stop everything matching `name`" behaviour) and a `verify`
+ * boolean that triggers post-launch verification. The route already
+ * required `name` even when `runId` was supplied — so no
+ * cross-field refine like /stop has.
+ */
+export declare const PostRelaunchAppRequestSchema: z.ZodPipe<z.ZodPipe<z.ZodObject<{
+    name: z.ZodString;
+    runId: z.ZodOptional<z.ZodString>;
+    verify: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodTransform<{
+    verify?: boolean | undefined;
+    runId?: string | undefined;
+    name: string;
+}, {
+    name: string;
+    runId?: string | undefined;
+    verify?: boolean | undefined;
+}>>, z.ZodObject<{
+    name: z.ZodString;
+    runId: z.ZodOptional<z.ZodString>;
+    verify: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>>;
+/**
+ * /create maps onto the unified APP action — the `intent` is the
+ * natural-language prompt the orchestrator hands to the spawned coding
+ * sub-agent, and `editTarget` (when present) names an existing app to
+ * edit instead of scaffolding a new one. The handler used to require a
+ * non-empty trimmed intent by hand; the schema now does that, plus
+ * trims `editTarget` so empty strings round-trip back to "missing".
+ */
+export declare const PostCreateAppRequestSchema: z.ZodPipe<z.ZodPipe<z.ZodObject<{
+    intent: z.ZodString;
+    editTarget: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodTransform<{
+    editTarget?: string | undefined;
+    intent: string;
+}, {
+    intent: string;
+    editTarget?: string | undefined;
+}>>, z.ZodObject<{
+    intent: z.ZodString;
+    editTarget: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+/**
+ * /overlay-presence is the UI's "which app is currently visible" ping.
+ * The route accepts a string, an explicit `null`, or omission — all of
+ * the latter two clear presence. Empty/whitespace strings collapse to
+ * null too, matching the handler's prior `trim().length > 0 ? trim : null`
+ * normalisation.
+ */
+export declare const PostOverlayPresenceRequestSchema: z.ZodPipe<z.ZodObject<{
+    appName: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+}, z.core.$strict>, z.ZodTransform<{
+    appName: string | null;
+}, {
+    appName?: string | null | undefined;
+}>>;
+/** /overlay-presence reply: `{ ok: true, appName: string | null }`. */
+export declare const PostOverlayPresenceResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    appName: z.ZodUnion<readonly [z.ZodString, z.ZodNull]>;
+}, z.core.$strict>;
+/** /create reply from the unified APP action. */
+export declare const PostCreateAppResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    text: z.ZodString;
+    messages: z.ZodArray<z.ZodString>;
+    data: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strict>;
+/** /refresh reply — registry refresh count. */
+export declare const PostRefreshAppsResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    count: z.ZodNumber;
+}, z.core.$strict>;
+/**
+ * Component schema: install-progress event the installer streams as it
+ * walks through phases (download, extract, register, …). Mirrors the
+ * `InstallProgressLike` interface in
+ * `packages/agent/src/services/plugin-manager-types.ts`.
+ */
+export declare const InstallProgressEventSchema: z.ZodObject<{
+    phase: z.ZodString;
+    message: z.ZodString;
+    pluginName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * /install reply, discriminated on `success`:
+ *   - success: full install metadata + replayed progress events
+ *   - failure: error + the progress events that were captured before
+ *     the failure
+ */
+export declare const PostInstallAppResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    pluginName: z.ZodString;
+    version: z.ZodString;
+    installPath: z.ZodString;
+    requiresRestart: z.ZodBoolean;
+    progress: z.ZodArray<z.ZodObject<{
+        phase: z.ZodString;
+        message: z.ZodString;
+        pluginName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    error: z.ZodOptional<z.ZodString>;
+    progress: z.ZodArray<z.ZodObject<{
+        phase: z.ZodString;
+        message: z.ZodString;
+        pluginName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "success">;
+export type PostLaunchAppRequest = z.infer<typeof PostLaunchAppRequestSchema>;
+export type PostInstallAppRequest = z.infer<typeof PostInstallAppRequestSchema>;
+export type PostStopAppRequest = z.infer<typeof PostStopAppRequestSchema>;
+export type PostRelaunchAppRequest = z.infer<typeof PostRelaunchAppRequestSchema>;
+export type PostCreateAppRequest = z.infer<typeof PostCreateAppRequestSchema>;
+export type PostOverlayPresenceRequest = z.infer<typeof PostOverlayPresenceRequestSchema>;
+export type PostOverlayPresenceResponse = z.infer<typeof PostOverlayPresenceResponseSchema>;
+export type PostCreateAppResponse = z.infer<typeof PostCreateAppResponseSchema>;
+export type PostRefreshAppsResponse = z.infer<typeof PostRefreshAppsResponseSchema>;
+export type InstallProgressEvent = z.infer<typeof InstallProgressEventSchema>;
+export type PostInstallAppResponse = z.infer<typeof PostInstallAppResponseSchema>;
+//# sourceMappingURL=apps-lifecycle-routes.d.ts.map

package/contracts/apps-lifecycle-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps-lifecycle-routes.d.ts","sourceRoot":"","sources":["../../src/contracts/apps-lifecycle-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,CAAC,MAAM,KAAK,CAAC;AAepB,eAAO,MAAM,0BAA0B;;;;;;;;mBAEmC,CAAC;AAE3E,eAAO,MAAM,2BAA2B;;;;;;;;;;;;mBAkBrC,CAAC;AAEJ;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;GAehC,CAAC;AAEN;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;mBAoBtC,CAAC;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;mBAiBpC,CAAC;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC;;;aAKZ,MAAM,GAAG,IAAI;;;GAI1C,CAAC;AASL,uEAAuE;AACvE,eAAO,MAAM,iCAAiC;;;kBAKnC,CAAC;AAEZ,iDAAiD;AACjD,eAAO,MAAM,2BAA2B;;;;;kBAO7B,CAAC;AAEZ,+CAA+C;AAC/C,eAAO,MAAM,6BAA6B;;;kBAK/B,CAAC;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B;;;;kBAM5B,CAAC;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;+BAkBvC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC1C,OAAO,4BAA4B,CACpC,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,gCAAgC,CACxC,CAAC;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,iCAAiC,CACzC,CAAC;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC1C,OAAO,4BAA4B,CACpC,CAAC"}

package/contracts/apps-lifecycle-routes.js

@@ -0,0 +1,204 @@
+/**
+ * Zod schemas for the apps-lifecycle HTTP routes
+ * (launch / install / stop / relaunch / create / overlay-presence /
+ * refresh). Same template as the rest: schema in shared, safeParse on
+ * server, infer types on client.
+ *
+ * Routes covered:
+ *   POST /api/apps/launch            body: { name }                  → AppLaunchResult
+ *   POST /api/apps/install           body: { name, version? }        → InstallAppResponse
+ *   POST /api/apps/stop              body: { name?, runId? }         → AppStopResult
+ *                                     (at least one of name/runId required)
+ *   POST /api/apps/relaunch          body: { name, runId?, verify? } → AppLaunchResult
+ *   POST /api/apps/create            body: { intent, editTarget? }   → CreateAppResponse
+ *   POST /api/apps/overlay-presence  body: { appName?: string|null } → OverlayPresenceResponse
+ *   POST /api/apps/refresh           (no body)                       → RefreshAppsResponse
+ *
+ * Response shapes for the routes that delegate to AppLaunchResult or
+ * AppStopResult (launch, stop, relaunch) are still defined by the
+ * TypeScript interfaces in `./apps.ts` — those tree types have not
+ * been migrated to zod yet and are out of scope for this module.
+ */
+import z from "zod";
+/** Request body shared by /launch and /install. */
+const NameOnlyRequestBase = z
+    .object({
+    name: z.string().min(1, "name is required"),
+})
+    .strict();
+/** Trims `name` to match the server's pre-zod normalisation. */
+const trimName = (value) => ({
+    ...value,
+    name: value.name.trim(),
+});
+export const PostLaunchAppRequestSchema = NameOnlyRequestBase.transform(trimName).pipe(z.object({ name: z.string().min(1, "name is required") }).strict());
+export const PostInstallAppRequestSchema = z
+    .object({
+    name: z.string().min(1, "name is required"),
+    version: z.string().min(1).optional(),
+})
+    .strict()
+    .transform((value) => ({
+    ...value,
+    name: value.name.trim(),
+    ...(value.version ? { version: value.version.trim() } : {}),
+}))
+    .pipe(z
+    .object({
+    name: z.string().min(1, "name is required"),
+    version: z.string().min(1).optional(),
+})
+    .strict());
+/**
+ * /stop accepts `{ name }`, `{ runId }`, or both — but at least one
+ * must be a non-empty string. The `.refine()` does the cross-field
+ * check the route used to do by hand.
+ */
+export const PostStopAppRequestSchema = z
+    .object({
+    name: z.string().min(1).optional(),
+    runId: z.string().min(1).optional(),
+})
+    .strict()
+    .refine((value) => (value.name && value.name.trim().length > 0) ||
+    (value.runId && value.runId.trim().length > 0), { message: "name or runId is required" })
+    .transform((value) => ({
+    ...(value.name ? { name: value.name.trim() } : {}),
+    ...(value.runId ? { runId: value.runId.trim() } : {}),
+}));
+/**
+ * /relaunch accepts the launch fields plus optional `runId` (used to
+ * stop a specific run before relaunching, instead of the broader
+ * "stop everything matching `name`" behaviour) and a `verify`
+ * boolean that triggers post-launch verification. The route already
+ * required `name` even when `runId` was supplied — so no
+ * cross-field refine like /stop has.
+ */
+export const PostRelaunchAppRequestSchema = z
+    .object({
+    name: z.string().min(1, "name is required"),
+    runId: z.string().min(1).optional(),
+    verify: z.boolean().optional(),
+})
+    .strict()
+    .transform((value) => ({
+    name: value.name.trim(),
+    ...(value.runId ? { runId: value.runId.trim() } : {}),
+    ...(typeof value.verify === "boolean" ? { verify: value.verify } : {}),
+}))
+    .pipe(z
+    .object({
+    name: z.string().min(1, "name is required"),
+    runId: z.string().min(1).optional(),
+    verify: z.boolean().optional(),
+})
+    .strict());
+/**
+ * /create maps onto the unified APP action — the `intent` is the
+ * natural-language prompt the orchestrator hands to the spawned coding
+ * sub-agent, and `editTarget` (when present) names an existing app to
+ * edit instead of scaffolding a new one. The handler used to require a
+ * non-empty trimmed intent by hand; the schema now does that, plus
+ * trims `editTarget` so empty strings round-trip back to "missing".
+ */
+export const PostCreateAppRequestSchema = z
+    .object({
+    intent: z.string().min(1, "intent is required"),
+    editTarget: z.string().min(1).optional(),
+})
+    .strict()
+    .transform((value) => ({
+    intent: value.intent.trim(),
+    ...(value.editTarget ? { editTarget: value.editTarget.trim() } : {}),
+}))
+    .pipe(z
+    .object({
+    intent: z.string().min(1, "intent is required"),
+    editTarget: z.string().min(1).optional(),
+})
+    .strict());
+/**
+ * /overlay-presence is the UI's "which app is currently visible" ping.
+ * The route accepts a string, an explicit `null`, or omission — all of
+ * the latter two clear presence. Empty/whitespace strings collapse to
+ * null too, matching the handler's prior `trim().length > 0 ? trim : null`
+ * normalisation.
+ */
+export const PostOverlayPresenceRequestSchema = z
+    .object({
+    appName: z.union([z.string(), z.null()]).optional(),
+})
+    .strict()
+    .transform((value) => {
+    const raw = value.appName;
+    const trimmed = typeof raw === "string" ? raw.trim() : "";
+    return { appName: trimmed.length > 0 ? trimmed : null };
+});
+// ── Response schemas ─────────────────────────────────────────────────
+//
+// Only the inline ad-hoc shapes the handlers produce are modelled here.
+// Routes returning AppLaunchResult / AppStopResult (launch, relaunch,
+// stop) keep using the TS interfaces in `./apps.ts` — migrating those
+// tree types is a separate pass.
+/** /overlay-presence reply: `{ ok: true, appName: string | null }`. */
+export const PostOverlayPresenceResponseSchema = z
+    .object({
+    ok: z.literal(true),
+    appName: z.union([z.string().min(1), z.null()]),
+})
+    .strict();
+/** /create reply from the unified APP action. */
+export const PostCreateAppResponseSchema = z
+    .object({
+    success: z.boolean(),
+    text: z.string(),
+    messages: z.array(z.string()),
+    data: z.nullable(z.unknown()),
+})
+    .strict();
+/** /refresh reply — registry refresh count. */
+export const PostRefreshAppsResponseSchema = z
+    .object({
+    ok: z.literal(true),
+    count: z.number().int().nonnegative(),
+})
+    .strict();
+/**
+ * Component schema: install-progress event the installer streams as it
+ * walks through phases (download, extract, register, …). Mirrors the
+ * `InstallProgressLike` interface in
+ * `packages/agent/src/services/plugin-manager-types.ts`.
+ */
+export const InstallProgressEventSchema = z
+    .object({
+    phase: z.string(),
+    message: z.string(),
+    pluginName: z.string().optional(),
+})
+    .strict();
+/**
+ * /install reply, discriminated on `success`:
+ *   - success: full install metadata + replayed progress events
+ *   - failure: error + the progress events that were captured before
+ *     the failure
+ */
+export const PostInstallAppResponseSchema = z.discriminatedUnion("success", [
+    z
+        .object({
+        success: z.literal(true),
+        pluginName: z.string(),
+        version: z.string(),
+        installPath: z.string(),
+        requiresRestart: z.boolean(),
+        progress: z.array(InstallProgressEventSchema),
+    })
+        .strict(),
+    z
+        .object({
+        success: z.literal(false),
+        error: z.string().optional(),
+        progress: z.array(InstallProgressEventSchema),
+    })
+        .strict(),
+]);
+//# sourceMappingURL=apps-lifecycle-routes.js.map