@hypit/hypit 0.2.1 → 0.2.3

package/README.md

@@ -147,11 +147,39 @@ commands and the repository layout.
 ## Launch Partner
 
 <table>
+  <tr>
+    <td width="220" align="center">
+      <a href="https://watcha.cn">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="./docs/public/watcha-dark.png">
+          <img alt="Watcha" src="./docs/public/watcha-light.png" width="170">
+        </picture>
+      </a>
+    </td>
+    <td><a href="https://watcha.cn">Watcha</a> is an innovative ecosystem and community built for AI builders, connecting great products with high-quality users to turn every Demo into reality. Starting from AI product discovery and genuine feedback, Watcha provides product publishing, distribution, and reputation tracking to support builders from launch to early adoption.</td>
+  </tr>
+  <tr>
+    <td width="220" align="center">
+      <a href="https://tokendance.space/?utm_source=hypit">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="./docs/public/tokendance-dark.png">
+          <img alt="TokenDance" src="./docs/public/tokendance-light.png" width="165">
+        </picture>
+      </a>
+    </td>
+    <td><a href="https://tokendance.space/?utm_source=hypit">TokenDance</a> offers builders a unified multi-model gateway with optimized inference costs. Through programs like the Billion-Token Subsidy and the Developer Program, TokenDance helps early-stage builders cut costs so they can focus on product validation and growth.</td>
+  </tr>
+  <tr>
+    <td width="220" align="center">
+      <a href="https://autoclaw.z.ai"><img alt="AutoClaw" src="./docs/public/autoclaw.png" width="180"></a>
+    </td>
+    <td><a href="https://autoclaw.z.ai">AutoClaw</a> is Z.ai’s desktop AI assistant for work, deeply optimized for GLM models and integrated with specialized knowledge bases and workflows for legal, finance, design, and more.</td>
+  </tr>
   <tr>
     <td width="220" align="center">
       <a href="https://openagents.org/blog/posts/2026-09-08-pilot-user-program-zh-hypit"><img alt="OpenAgents" src="./docs/public/openagents.png" width="180"></a>
     </td>
-    <td>OpenAgents Workspace is a product that helps you manage AI agents, allowing you to invoke agents running on any device (whether on a mobile phone or computer) anytime, anywhere. Agents can collaborate within the platform to help you complete tasks and boost efficiency. It currently supports integration with over 20 types of agents, including Claude, Codex, OpenClaw, and Hermes (<a href="https://openagents.org">https://openagents.org</a>)</td>
+    <td><a href="https://openagents.org">OpenAgents Workspace</a> is a product that helps you manage AI agents, allowing you to invoke agents running on any device (whether on a mobile phone or computer) anytime, anywhere. Agents can collaborate within the platform to help you complete tasks and boost efficiency. It currently supports integration with over 20 types of agents, including Claude, Codex, OpenClaw, and Hermes.</td>
   </tr>
   <tr>
     <td width="220" align="center">
@@ -162,13 +190,19 @@ commands and the repository layout.
         </picture>
       </a>
     </td>
-    <td>Monid is the OpenRouter for agent tools: one key, one wallet, hundreds of tools, billed per call. Hypit can route Seedance video, images, speech and word-level transcription to Monid.</td>
+    <td><a href="https://monid.ai?fpr=alvin-45480b">Monid</a> is the OpenRouter for agent tools: one key, one wallet, hundreds of tools, billed per call. Hypit can route Seedance video, images, speech and word-level transcription to Monid.</td>
+  </tr>
+  <tr>
+    <td width="220" align="center">
+      <a href="https://www.hiapi.ai/invite/hypit"><img alt="HiAPI" src="./docs/public/hiapi.png" width="165"></a>
+    </td>
+    <td><a href="https://www.hiapi.ai/invite/hypit">HiAPI</a> is a unified API platform for AI image, video, audio, and language models. Connect GPT Image 2.5, Seedance 2.0, Veo 3.1, Kling, Wan, and other popular models through one platform. Pay as you go with no monthly fee, with free trial credits available for new users.</td>
   </tr>
   <tr>
     <td width="220" align="center">
-      <a href="https://www.hiapi.ai"><img alt="HiAPI" src="./docs/public/hiapi.png" width="165"></a>
+      <a href="https://api.pollo.ai/?utm_source=hypit"><img alt="Pollo API" src="./docs/public/pollo.jpg" width="120"></a>
     </td>
-    <td>HiAPI is a unified API platform for AI image, video, audio, and language models. Connect GPT Image 2.5, Seedance 2.0, Veo 3.1, Kling, Wan, and other popular models through one platform. Pay as you go with no monthly fee, with free trial credits available for new users.</td>
+    <td><a href="https://api.pollo.ai/?utm_source=hypit">Pollo API</a> gives developers access to 300+ AI image and video models through a single API, with competitive rates. One API key connects you to multiple model providers and scales from 10 to 10,000+ requests.</td>
   </tr>
 </table>
 

package/bin/hypit.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 import { register } from "tsx/esm/api";
-import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 if (process.argv.length === 3 && ["--version", "-v"].includes(process.argv[2])) {
   const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -18,27 +18,30 @@ process.emitWarning = function hypitWarning(warning, ...args) {
   return emitWarning.call(process, warning, ...args);
 };
 
-const distributionRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+// Bootstrap and package activation must agree on the physical Distribution root. Windows short
+// paths can survive Node's ordinary resolution while package lookup expands them through libuv.
+const distributionRoot = realpathSync.native(resolve(dirname(fileURLToPath(import.meta.url)), ".."));
+const distributionUrl = pathToFileURL(distributionRoot + sep);
 register();
 const {
   installDistributionPackageResolution,
   installExternalPackageResolution,
-} = await import("../packages/package-loader-node/src/distribution-resolution.ts");
+} = await import(new URL("packages/package-loader-node/src/distribution-resolution.ts", distributionUrl).href);
 installDistributionPackageResolution([distributionRoot]);
-const { hypitHostPackageRoot } = await import("../packages/runtime-host-node/src/index.ts");
+const { hypitHostPackageRoot } = await import(new URL("packages/runtime-host-node/src/index.ts", distributionUrl).href);
 installExternalPackageResolution([hypitHostPackageRoot()]);
 const args = process.argv.slice(2);
 if (args[0] === "studio" || (args[0] === "help" && args[1] === "studio")) {
-  const { runStudio } = await import("../packages/studio/start.ts");
+  const { runStudio } = await import(new URL("packages/studio/start.ts", distributionUrl).href);
   try {
     await runStudio(args[0] === "help" ? ["--help"] : args.slice(1).filter((arg) => arg !== "--debug"), {
       write: (text) => process.stdout.write(text),
     });
   } catch (error) {
-    const { renderCliError } = await import("../packages/cli/src/index.ts");
+    const { renderCliError } = await import(new URL("packages/cli/src/index.ts", distributionUrl).href);
     process.stderr.write(renderCliError(error, { debug: args.includes("--debug") }));
     process.exitCode = 1;
   }
 } else {
-  await import("../packages/video-cli/src/cli.ts");
+  await import(new URL("packages/video-cli/src/cli.ts", distributionUrl).href);
 }

package/dist/public/generation.d.ts

@@ -533,14 +533,13 @@ declare function selectWireModelForRequest(mapping: GenerationWireMapping, reque
  * only the mapping and the request, never the model package.
  */
 declare function compileWireRequest(mapping: GenerationWireMapping, request: GenerationRequest, resolve: GenerationArtifactUrlResolver): Promise<GenerationWireRequest>;
-/** Does this request only use ports this mapping can write? Needs no model package. */
+/** Optional fields may be omitted by authors, but supplied fields must reach the service. */
 declare function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean;
 /**
- * Prove one service mapping covers every port the model declares.
+ * Check structural port coverage and required item fields against the model declaration.
  *
- * This is the check the old hand-written per-model translators could not have:
- * a forgotten reference role or item field used to surface only after a paid
- * generation returned the wrong result.
+ * A service may omit optional item capabilities. mappingSupportsRequest and final compilation
+ * additionally refuse requests that actually supply such an unmapped field.
  */
 declare function assertMappingCoversPorts(table: GenerationPortTable, mapping: GenerationWireMapping): void;
 

package/examples/provider-package/README.md

@@ -1,10 +1,23 @@
 # A project-owned Provider
 
-This complete package demonstrates an asynchronous image service through the public Hypit SDK.
-The service protocol below is **illustrative**, not a live vendor API. Replace its mapping and
-transport with the selected service's documented operations. The lifecycle test exercises the
-example without a paid request. Implement the capabilities needed by the production; a service's
-entire catalogue is not required.
+This example shows a service that Hypit's official Distribution does not ship, implemented as a
+project package through the public Hypit SDK. Two packages cover the two request shapes a service
+usually differs on:
+
+| Package | Model | Request | Lifecycle |
+| --- | --- | --- | --- |
+| `packages/provider-images` | `@hypit/gpt-image@1#gpt-image-2` | one image, optional references | asynchronous |
+| `packages/provider-videos` | `@hypit/seedance@1#seedance-2-mini` | one video, references and frames | asynchronous |
+
+Both service protocols are **illustrative**, not live vendor APIs. Replace the mapping and transport
+with the selected service's documented operations. The lifecycle tests exercise the examples without
+a paid request. Implement the capabilities needed by the production; a service's entire catalogue is
+not required.
+
+The video example is the one to read when the service renders **video**. A video request carries the
+whole reference vocabulary — images, videos, audio and first/last frames — and the result is a large
+remote task rather than a returned file. This is the shape most third-party video services use, and
+the shape the official Distribution cannot supply for a service it does not know.
 
 ## Follow one request
 
@@ -46,25 +59,84 @@ does not claim remote cancellation.
 source and preserves the response with a concise description. It reads no graph and invents no
 future media duration. Rates and credentials do not supply spending permission.
 
+## Follow a video request
+
+A Seedance request reaches `@hypit/seedance@1#seedance-2-mini` and returns a generated video-set.
+The Model declares the request; this Provider decides how the service receives it. Four things
+differ from the image example, and each is the reason the video example exists.
+
+**The reference vocabulary is wider, and each role maps to its own field.** The Model declares
+`referenceImage`, `referenceVideo` and `referenceAudio` as separate ports precisely so each can map
+to one wire field — a service that mixes them into one array cannot tell the roles apart. An image
+reference also carries an optional `personReference` classification, which is why those ports use
+`itemObject` rather than `urlArray`: the item field travels with the URL it belongs to.
+
+```json
+{ "references": [{ "url": "https://…/reference.png", "person": true }] }
+```
+
+`firstFrame` and `lastFrame` accept at most one item each, so their body fields are URLs.
+This illustrative service accepts their optional person classification on `POST /uploads` through
+`x-person-reference: true` or `false`. Their mappings declare `resourceFields: ["personReference"]`,
+and the URL resolver sends that header when supplied. Replace this with the real service’s
+documented transport; a field that the service cannot carry must be refused, never discarded.
+
+**The service's range is narrower than the Model's, and the Provider states that.** Seedance 2 Mini
+admits 480p/720p and 4–15 seconds; this illustrative service renders 720p up to 10 seconds. The
+Model is not edited for that. `supports` reports the difference before submission, so `plan` refuses
+the request with a reason instead of failing a paid job downstream:
+
+```
+This service renders at most 10 seconds, not 12
+```
+
+Do not widen the Model to fit one service. Do not silently clamp the author's number either — the
+author wrote 12 seconds, and a 10-second result is a different video.
+
+**Submission is an enqueue, not the render.** `start` returns as soon as the service acknowledges a
+task, and the HTTP bound covers the API call, not the minutes the render may take. `poll` returns
+`pending` while the task is `queued` or `running`, and the task id is checkpointed before `start`
+returns, so an interrupted Build still names the remote work it began.
+
+**The result is fetched in a separate `collect` step.** A finished task carries a signed URL; the
+account key goes only to the service's own API. `collect` downloads the media, stores it through
+`context.resources` and returns the Model's declared value. Because `poll` and `collect` are
+separate actions, download capacity is configured independently of task capacity.
+
+A task that reports `succeeded` without an output URL is a service contract violation, not a pending
+job, and fails loudly. A `failed` task keeps the service's own error code and the received task id
+as evidence, and redacts URLs from the message it republishes.
+
+`assertMappingCoversPorts` checks declared ports and required item fields. Optional fields need
+request-level checks and transport tests as well:
+a mapping that forgets a reference role or an item field fails at load rather than after a paid
+generation returns the wrong video. Where a Model port is genuinely optional, `whenAbsent` states
+what the service should receive when the author omits it — the service then gets the value the
+author's request implies, not a field left to its own default. The lifecycle test asserts the
+mapping against the Model's own port table.
+
 ## Make it a package in the production
 
-Copy `packages/provider-images` into the video's `packages/`. Choose your own package name and change
-`providerModule.name` with it. Implement the actual service protocol, including its request limits,
-upload/download limits and any OAuth or cancellation behavior it really offers. Configure the
-selected service address; `images.example` is a placeholder that cannot generate media.
+Copy the package matching your service's request shape — `packages/provider-images` or
+`packages/provider-videos` — into the video's `packages/`. Choose your own package name and change
+`providerModule.name` with it. A service that renders both images and video can implement both
+capabilities in one package; `defineEndpointPackage` accepts several. Implement the actual service
+protocol, including its request limits, upload/download limits and any OAuth or cancellation
+behavior it really offers. Configure the selected service address; `images.example` and
+`videos.example` are placeholders that cannot generate media.
 
 Use the active `@hypit/hypit` version as a development dependency. Build and install with the
-project's package manager. In this repository the example uses `workspace:*` for that dependency;
-replace it with your selected release when copying it out. The `@hypit/driver-node` and
-`@hypit/gpt-image` development dependencies serve the repository test only and can be removed from
-the copied package. For example:
+project's package manager. In this repository the examples use `workspace:*` for that dependency;
+replace it with your selected release when copying it out. The `@hypit/driver-node` and model
+development dependencies (`@hypit/gpt-image`, `@hypit/seedance`) serve the repository tests only and
+can be removed from the copied package. For example:
 
 ```bash
-cd packages/provider-images
+cd packages/provider-videos
 npm install
 npm run build
 cd ../..
-npm install ./packages/provider-images
+npm install ./packages/provider-videos
 ```
 
 The package ships JavaScript. Its `hypit.activation` exports a Profile-selected Runtime facet;
@@ -73,10 +145,14 @@ loading project packages. Keep the chosen package version and lockfile with the
 
 Merge the endpoint, credential store and binding from `hypit.runtime.json` into the project's
 chosen Profile. Preserve its other services and resolve bindings explicitly. Once the user chooses
-that account, `hypit auth login images.personal` securely enters the key into its declared store.
+that account, `hypit auth login videos.personal` securely enters the key into its declared store.
 `plan` checks the requested parameters; `pricing` supplies the service's rates. Submitting a real
 generation follows the agreed production scope and spending authority.
 
+The service decides whether an Endpoint needs its own credential slot at all. A service that
+authenticates through the platform it runs on, or one reached at a private address, may declare no
+credentials or a non-secret account name; `defineEndpointPackage` takes whichever the service has.
+
 ## Owners
 
 - `src/provider.ts`: exact capability, mapping, service support, task lifecycle, pricing and capacity.

package/examples/provider-package/hypit.runtime.json

@@ -6,7 +6,14 @@
     "images.personal": {
       "use": "@example/provider-images",
       "config": { "baseUrl": "https://images.example", "apiKey": { "store": "platform", "key": "images.personal" } }
+    },
+    "videos.personal": {
+      "use": "@example/provider-videos",
+      "config": { "baseUrl": "https://videos.example", "apiKey": { "store": "platform", "key": "videos.personal" } }
     }
   },
-  "bindings": { "@hypit/gpt-image@1#gpt-image-2": "images.personal" }
+  "bindings": {
+    "@hypit/gpt-image@1#gpt-image-2": "images.personal",
+    "@hypit/seedance@1#seedance-2-mini": "videos.personal"
+  }
 }

package/examples/provider-package/packages/provider-videos/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@example/provider-videos",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "hypit": { "activation": "./dist/activation.js" },
+  "exports": { ".": "./dist/provider.js" },
+  "files": ["dist"],
+  "scripts": { "build": "tsc -p tsconfig.json" },
+  "devDependencies": { "@hypit/hypit": "workspace:*", "typescript": "5.9.3", "@hypit/driver-node": "workspace:*", "@hypit/seedance": "workspace:*" }
+}

package/examples/provider-package/packages/provider-videos/src/activation.ts

@@ -0,0 +1,24 @@
+import {
+  createRuntimeEndpointAdapterFacet, runtimeConfigCredentialRef, runtimeConfigExact,
+  runtimeConfigObject, runtimeConfigPositiveInteger, runtimeConfigString,
+} from "@hypit/hypit/runtime-kit";
+import { createVideoProvider, providerModule } from "./provider.js";
+
+export default {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [createRuntimeEndpointAdapterFacet({
+    use: providerModule.name,
+    activate(context) {
+      const config = runtimeConfigObject(context.config, "Video service");
+      runtimeConfigExact(config, ["baseUrl", "apiKey", "concurrency", "pollIntervalMs"], "Video service");
+      const baseUrl = runtimeConfigString(config.baseUrl, "Video service baseUrl");
+      const apiKey = runtimeConfigCredentialRef(config.apiKey, "Video service apiKey");
+      if (!baseUrl || !apiKey || !context.pool) throw new Error("Video service requires baseUrl, apiKey and pool");
+      return { endpoint: createVideoProvider({
+        instance: context.instance, pool: context.pool, baseUrl, apiKey,
+        concurrency: runtimeConfigPositiveInteger(config.concurrency, "concurrency") ?? 1,
+        pollIntervalMs: runtimeConfigPositiveInteger(config.pollIntervalMs, "pollIntervalMs") ?? 5_000,
+      }) };
+    },
+  })],
+};

package/examples/provider-package/packages/provider-videos/src/provider.ts

@@ -0,0 +1,181 @@
+import { canonicalize, defineEndpointPackage, wakeAfter } from "@hypit/hypit/endpoint-kit";
+import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "@hypit/hypit/endpoint-kit";
+import {
+  compileWireRequest, generationTypes, mappingSupportsRequest,
+  sealGeneratedVideoSet, selectWireModelForRequest,
+} from "@hypit/hypit/generation";
+import type { GenerationRequest, GenerationWireMapping } from "@hypit/hypit/generation";
+
+export const providerModule = { name: "@example/provider-videos", version: "1" } as const;
+export const capability = { module: { name: "@hypit/seedance", version: "1" }, name: "seedance-2-mini" } as const;
+
+// This example service implements only this subset of the model. Its API is described in README.
+export const mapping: GenerationWireMapping = {
+  capability, result: "video", routes: [{ model: "seedance-2-mini" }],
+  fields: {
+    prompt: { as: "value", field: "prompt" },
+    duration: { as: "value", field: "duration" },
+    resolution: { as: "value", field: "resolution" },
+    aspectRatio: { as: "value", field: "ratio" },
+    generateAudio: { as: "value", field: "audio" },
+    webSearch: { as: "value", field: "search" },
+    referenceImage: { as: "itemObject", field: "references", urlKey: "url", fieldKeys: { personReference: "person" } },
+    referenceVideo: { as: "itemObject", field: "videoReferences", urlKey: "url", fieldKeys: { personReference: "person" } },
+    referenceAudio: { as: "urlArray", field: "audioReferences" },
+    firstFrame: { as: "url", field: "firstFrame", resourceFields: ["personReference"] },
+    lastFrame: { as: "url", field: "lastFrame", resourceFields: ["personReference"] },
+  },
+};
+
+// This service renders a narrower band than the model vocabulary allows, which it reports rather
+// than widening: Seedance 2 Mini declares 480p/720p and 4–15 seconds, and this service renders 720p
+// up to 10 seconds. The Model is unchanged; the difference belongs to this Endpoint.
+const SUPPORTED_RESOLUTION = "720p";
+const SUPPORTED_SECONDS = 10;
+
+function object(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected service object");
+  return value as Record<string, unknown>;
+}
+function text(value: unknown): string {
+  if (typeof value !== "string" || value.length === 0) throw new Error("Expected nonempty service text");
+  return value;
+}
+// This illustrative service documents these fields as its public failure evidence.
+function publicFailure(value: unknown): { code: string; message: string } | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const error = value as Record<string, unknown>;
+  if (typeof error.code !== "string" || typeof error.message !== "string") return undefined;
+  return { code: error.code, message: error.message.replace(/https?:\/\/\S+/giu, "[redacted-url]") };
+}
+function address(value: string): string {
+  const url = new URL(value);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname))) {
+    throw new Error("Service URLs require HTTPS or loopback HTTP");
+  }
+  return url.href;
+}
+
+function serviceSupport(request: EndpointRequest) {
+  const ports = (request.constraints as unknown as GenerationRequest).ports;
+  const duration = ports.duration?.[0];
+  if (typeof duration === "number" && duration > SUPPORTED_SECONDS) {
+    return { status: "unsupported" as const,
+      reason: `This service renders at most ${SUPPORTED_SECONDS} seconds, not ${duration}` };
+  }
+  const resolution = ports.resolution?.[0];
+  if (resolution !== undefined && String(resolution) !== SUPPORTED_RESOLUTION) {
+    return { status: "unsupported" as const,
+      reason: `This service renders at ${SUPPORTED_RESOLUTION}, not ${String(resolution)}` };
+  }
+  return mappingSupportsRequest(mapping, request.constraints)
+    ? { status: "supported" as const }
+    : { status: "unsupported" as const, reason: "This service does not accept one of the requested inputs" };
+}
+
+export function createVideoProvider(options: {
+  instance: string; pool: string; baseUrl: string; apiKey: CredentialRef;
+  concurrency?: number; pollIntervalMs?: number; fetch?: typeof globalThis.fetch;
+}) {
+  const base = address(options.baseUrl).replace(/\/$/u, "");
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const interval = options.pollIntervalMs ?? 5_000;
+  const key = (credentials: Readonly<Record<string, { secret: string }>>) => text(credentials.apiKey?.secret);
+  async function json(path: string, secret: string, init: RequestInit = {}) {
+    const response = await fetcher(`${base}${path}`, {
+      ...init, headers: { ...init.headers, authorization: `Bearer ${secret}` },
+      // Submission enqueues a remote job and answers immediately; the bound is for the API, not the render.
+      signal: AbortSignal.timeout(120_000),
+    });
+    if (!response.ok) {
+      let error: ReturnType<typeof publicFailure>;
+      try { error = publicFailure(object(await response.json()).error); }
+      catch { /* A missing public error body leaves the HTTP evidence intact. */ }
+      const requestId = response.headers.get("x-request-id");
+      throw Object.assign(new Error(`Video service ${init.method ?? "GET"} ${path} returned HTTP ${response.status}`
+        + (requestId === null ? "" : `; request=${requestId}`)
+        + (error === undefined ? "" : `; ${error.code}: ${error.message}`)),
+      error === undefined ? {} : { code: error.code });
+    }
+    return object(await response.json());
+  }
+  const endpoint: AsyncEndpoint = {
+    async start(context) {
+      const supported = serviceSupport(context.need);
+      if (supported.status === "unsupported") throw new Error(supported.reason);
+      const secret = key(context.credentials);
+      const authored = context.need.constraints as unknown as GenerationRequest;
+      const model = selectWireModelForRequest(mapping, authored);
+      // This service has no catalogue query; its known request limits were checked above.
+      await context.reportProgress?.({ phase: `Preparing video request: ${model}` });
+      const request = await compileWireRequest(mapping, authored,
+        async (artifact, fields) => {
+          const bytes = await context.resources.get(artifact.resource);
+          if (bytes === undefined) throw new Error("Reference media is unavailable");
+          const upload = await fetcher(`${base}/uploads`, {
+            method: "POST", headers: { "content-type": artifact.mediaType, authorization: `Bearer ${secret}`,
+              ...(fields?.personReference === undefined ? {} : { "x-person-reference": String(fields.personReference) }),
+            },
+            body: new Blob([new Uint8Array(bytes)]), signal: AbortSignal.timeout(120_000),
+          });
+          if (!upload.ok) throw new Error(`Video service POST /uploads returned HTTP ${upload.status}`);
+          return address(text(object(await upload.json()).url));
+        });
+      await context.reportProgress?.({ phase: `Submitting video request: ${model}` });
+      const task = await json("/videos", secret, {
+        method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(request),
+      });
+      const id = text(task.id), handle = { id }, receipt = { id };
+      await context.checkpoint?.({ handle, receipt });
+      return { ...wakeAfter(handle, interval), receipt };
+    },
+    async poll(context) {
+      const id = text(object(context.handle).id);
+      const task = await json(`/videos/${encodeURIComponent(id)}`, key(context.credentials));
+      const status = text(task.status);
+      if (status === "queued" || status === "running") {
+        return wakeAfter({ id }, interval, Date.now(), { phase: status });
+      }
+      if (status === "failed") {
+        const error = publicFailure(task.error);
+        return { status: "failed", receipt: { id }, failure: {
+          code: error?.code ?? "VIDEO_SERVICE_FAILED",
+          message: `Video service task ${id} failed${error === undefined ? "" : `: ${error.message}`}`,
+        } };
+      }
+      if (status !== "succeeded") throw new Error("Video service returned an unknown task state");
+      // A completed task without a result URL is a service contract violation, not a pending job.
+      return { status: "ready", handle: { id, url: address(text(task.output)) } };
+    },
+    async collect(context) {
+      // The service returns a signed asset URL; account credentials go only to its API.
+      const url = address(text(object(context.handle).url));
+      await context.reportProgress?.({ phase: "Receiving generated video" });
+      // One delivered video is bounded here; a larger file belongs with a streaming resource port.
+      const response = await fetcher(url, { signal: AbortSignal.timeout(600_000) });
+      if (!response.ok) throw new Error(`Video download returned HTTP ${response.status}`);
+      const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim();
+      if (!mediaType?.startsWith("video/")) throw new Error("Video service returned a non-video result");
+      const artifact = await context.resources.put(new Uint8Array(await response.arrayBuffer()), mediaType);
+      return { status: "completed", result: { value: {
+        kind: "inline", value: canonicalize(sealGeneratedVideoSet({ videos: [artifact] })),
+      } } };
+    },
+  };
+  return defineEndpointPackage({
+    module: providerModule, facet: "videos", instance: options.instance, pool: options.pool,
+    credentials: { apiKey: options.apiKey }, credentialInputs: { apiKey: { label: "Video service API key" } },
+    defaultConcurrency: options.concurrency ?? 1,
+    actionLimits: { submit: { concurrency: 1 }, poll: { concurrency: 4 }, collect: { concurrency: 2 } },
+    pricing: { kind: "page", url: `${base}/pricing` },
+    async readPricing(context) {
+      const model = selectWireModelForRequest(mapping, context.request.constraints as unknown as GenerationRequest,
+        context.request.pendingInputs?.map((input) => input.input));
+      const path = `/rates?model=${encodeURIComponent(model)}`;
+      const source = `${base}${path}`;
+      const rates = await json(path, key(await context.credentials()));
+      return [{ source, data: canonicalize(rates), summary: text(rates.description) }];
+    },
+    capabilities: [{ capability, returns: generationTypes.videoSet, lifecycle: "asynchronous", supports: serviceSupport, endpoint }],
+  });
+}

package/examples/provider-package/packages/provider-videos/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "target": "ES2023", "module": "NodeNext", "moduleResolution": "NodeNext",
+    "lib": ["ES2023", "DOM"], "strict": true, "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true, "verbatimModuleSyntax": true,
+    "declaration": true, "rootDir": "src", "outDir": "dist", "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",

package/packages/build-result/package.json

@@ -9,6 +9,6 @@
   },
   "dependencies": {
     "@hypit/protocol": "workspace:*",
-    "koffi": "3.2.1"
+    "@hypit/file-io-node": "workspace:*"
   }
 }

package/packages/build-result/src/store.ts

@@ -43,7 +43,7 @@ import {
   encodeBuildResultManifest,
 } from "./decode.js";
 import { syncBuildResultOutputs } from "./writer.js";
-import { replaceFile } from "./replace-file.js";
+import { replaceFile } from "@hypit/file-io-node";
 
 const manifestName = "result.json";
 const writerStateName = ".writer.json";

package/packages/caption-fine-studio/package.json

@@ -17,6 +17,6 @@
     "@hypit/studio-adapter": "workspace:*",
     "@hypit/fonts-open": "workspace:*",
     "@hypit/caption": "workspace:*",
-    "@hypit/timeline": "workspace:*"
+    "@hypit/temporal": "workspace:*"
   }
 }

package/packages/cli/src/commands/environment.ts

@@ -172,7 +172,9 @@ export async function runEnvironmentCommand(input: {
   }
 
   if (args.command === "programs") {
-    if (runtimeProfile === undefined) throw new Error("programs requires a Runtime Profile");
+    if (runtimeProfile === undefined) {
+      throw new Error("programs requires a Runtime; run hypit runtime init, select one with runtime use, or pass --runtime <profile>");
+    }
     const profile = resolve(runtimeProfile);
     const host = await runtimeHost(profile);
     if (args.action === "up" || args.action === "prepare") {
@@ -195,11 +197,13 @@ export async function runEnvironmentCommand(input: {
         : await controller.programs.report(args.endpoints === undefined ? {} : { endpoints: args.endpoints });
     const ready = result.programs.every((item) => item.state.state === "ready");
     const needsAttention = (item: typeof result.programs[number]) => args.action === "down"
-      ? item.state.state !== "down" || (item.action !== "stopped" && item.action !== "nothing-to-stop")
+      ? item.action !== "nothing-to-stop"
+        && (item.state.state !== "down" || item.action !== "stopped")
       : item.state.state !== "ready";
     // Readiness describes the service, not whether a stop was performed. An owned process can
     // still be loading, and another command may have declined a concurrent stop during preparation.
     const lifecycleOk = args.action === "status" || !result.programs.some(needsAttention);
+    const stoppedAny = result.programs.some((item) => item.action === "stopped");
     const relevant = result.programs.filter((item) => args.presentation.verbose || args.action === "status" || needsAttention(item));
     const urgent = relevant.filter(needsAttention);
     const shownPrograms = [...urgent, ...relevant.filter((item) => !needsAttention(item)).slice(0, Math.max(0, args.limit - urgent.length))];
@@ -209,7 +213,8 @@ export async function runEnvironmentCommand(input: {
       : args.action === "up"
       ? lifecycleOk ? "External programs ready" : "External programs need attention"
       : args.action === "down"
-        ? lifecycleOk ? "External programs stopped" : "External program stop needs attention"
+        ? lifecycleOk ? stoppedAny ? "External programs stopped" : "No external programs to stop"
+          : "External program stop needs attention"
         : "External program status";
     write({
       format: "hypit.cli-programs@1",
@@ -232,7 +237,9 @@ export async function runEnvironmentCommand(input: {
   }
 
   if (args.command === "runtime") {
-    if (runtimeProfile === undefined) throw new Error("runtime requires a Runtime Profile");
+    if (runtimeProfile === undefined) {
+      throw new Error("runtime requires a Runtime; run hypit runtime init, select one with runtime use, or pass --runtime <profile>");
+    }
     const profile = resolve(runtimeProfile);
     const controller = await runtimeController(profile);
     if (args.action === "up") {
@@ -298,7 +305,7 @@ export async function runEnvironmentCommand(input: {
       write({ format: "hypit.cli-runtime-down@1", worker: worker.state },
         stopped ? "Runtime Worker is down" : "Runtime Worker is still running",
         stopped ? "success" : "warning", [["Worker", worker.state]],
-        [`Managed programs were left running. To stop them: ${commandHint(["programs", "down"], { projectRoot, runtimeProfile: resolve(profile) })}`]);
+        [`Managed Programs are unchanged. To stop processes started by Hypit: ${commandHint(["programs", "down"], { projectRoot, runtimeProfile: resolve(profile) })}`]);
       if (!stopped) io.setExitCode?.(1);
       return;
     }

package/packages/cli/src/output.ts

@@ -1015,7 +1015,7 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
     row("doctor [profile]", "diagnose selected external setup"),
     row("runtime init|use|unset", "create or select this project's Runtime Profile"),
     row("runtime up|status|logs|down", "prepare and manage the local Build Runtime"),
-    row("programs up|status|down", "manage declared external programs only"),
+    row("programs prepare|up|status|down", "manage declared external programs only"),
     row("packages install|status", "manage pinned upstream packages in the machine home"),
     row("activity [--watch]", "show active Builds and their current phases"),
     row("cancel <build-id>", "withdraw one active Build"),