cortico 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phantivia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+<!-- Owner: scripts/publish-package.ts, src/extensions/runtime.ts -->
+
+# cortico
+
+Framework sources for [Cortico](https://github.com/Pal-AI-Lab/Cortico), published so that an
+extension package resolves `cortico/*` while it is being written.
+
+An extension supplies one World, one provider or one bot, and imports the framework by its path
+under `src/`:
+
+```ts
+import type { WorldDefinition } from 'cortico/world.ts';
+import type { EventEnvelope, WorldHost } from 'cortico/core/types.ts';
+```
+
+Inside a running instance those specifiers are resolved by the host's module hook to the
+framework that instance runs. This package supplies the same files to the editor, the type
+checker and the test runner before the extension is installed anywhere, which is the whole of
+what it does: it has no entry point and starts nothing.
+
+## Install
+
+```bash
+pnpm add -D cortico
+```
+
+The extension contract is API version 4; a package declares it as `"cortico": { "kind": ..., "api": 4 }`
+in its own `package.json`. This package's minor version tracks the framework, so pin the range
+your extension was written against.
+
+`templates/extension/` in the repository holds a ready package for each kind, and
+[docs/extensions.md](https://github.com/Pal-AI-Lab/Cortico/blob/main/docs/extensions.md) states
+the packaging rules.
+
+## Running a bot
+
+Running Cortico itself means cloning the repository; deployments, bot packages and the web
+console live in the checkout.
+
+```bash
+git clone https://github.com/Pal-AI-Lab/Cortico.git
+cd Cortico
+corepack pnpm install
+pnpm start
+```
+
+MIT licensed.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "cortico",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A TypeScript framework for event-driven, long-running persona bots",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Pal-AI-Lab/Cortico.git"
+  },
+  "homepage": "https://github.com/Pal-AI-Lab/Cortico#readme",
+  "bugs": {
+    "url": "https://github.com/Pal-AI-Lab/Cortico/issues"
+  },
+  "keywords": [
+    "cortico",
+    "agent",
+    "persona",
+    "bot",
+    "framework",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    "./*": "./src/*"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@types/express": "^4.17.21",
+    "@types/ws": "^8.5.13",
+    "express": "^4.21.2",
+    "fflate": "0.8.3",
+    "tar-stream": "3.2.1",
+    "ws": "^8.18.0"
+  }
+}

package/src/boot.ts

@@ -0,0 +1,46 @@
+/**
+ * 向 bin/cortico.mjs 请求重启。先写标志文件，再发 IPC 消息，文件作为通知中断时的 fallback。
+ * 仅在 CORTICO_SUPERVISED 启用时使用 IPC；其他宿主可能将同一通道用于自己的协议。
+ */
+import { existsSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const RESTART_FLAG_FILE = '.restart-request';
+
+/** 表示进程由支持重启的启动器监管。 */
+export const SUPERVISED_ENV = 'CORTICO_SUPERVISED';
+
+/** 与 bin/cortico.mjs 的 RESTART_MESSAGE 保持一致。 */
+export const RESTART_MESSAGE = 'cortico:restart';
+/** 上报 data 目录；与 bin/cortico.mjs 的 READY_MESSAGE 保持一致。 */
+export const READY_MESSAGE = 'cortico:ready';
+
+export function isSupervised(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env[SUPERVISED_ENV] === '1' || env[SUPERVISED_ENV] === 'true';
+}
+
+function notifyLauncher(message: { type: string; dataDir?: string }, env = process.env): void {
+  if (!isSupervised(env)) return;
+  process.send?.(message);
+}
+
+export function announceDataDir(dataDir: string, env = process.env): void {
+  notifyLauncher({ type: READY_MESSAGE, dataDir }, env);
+}
+
+/** 请求重启后，由调用方执行关机。 */
+export function requestRestart(dataDir: string, env = process.env): void {
+  writeFileSync(join(dataDir, RESTART_FLAG_FILE), new Date().toISOString() + '\n', 'utf8');
+  notifyLauncher({ type: RESTART_MESSAGE }, env);
+}
+
+export function consumeBootFlags(dataDir: string): void {
+  const restartFlag = join(dataDir, RESTART_FLAG_FILE);
+  if (existsSync(restartFlag)) {
+    try {
+      rmSync(restartFlag);
+    } catch {
+      // 启动器也会删除此标志；直接启动时残留文件不触发重启。
+    }
+  }
+}