@app-agents/core 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared types for app-agents.
+ *
+ * One app manifest describes one app, the expert agents inside it, and
+ * exactly what those agents are allowed to do. The manifest is the source of
+ * truth for the registry, the CLI, and the "what can you promise a customer"
+ * answer.
+ */
+export type CapabilityLevel = 'read' | 'write' | 'confirm';
+export type ExpertStatus = 'stable' | 'beta' | 'gap';
+export interface ExpertManifest {
+    /** Job name inside the app, e.g. `campaign_report`. */
+    id: string;
+    /** Human label, e.g. "Campaign report". */
+    title: string;
+    /** One sentence: the decision this agent makes that a tool call cannot. */
+    job: string;
+    status: ExpertStatus;
+    /** Entry agent name exported by the package. Absent while status is `gap`. */
+    agent?: string;
+    /** action -> permission level. Nothing not listed here is reachable. */
+    capabilities: Record<string, CapabilityLevel>;
+}
+export interface CredentialRequirement {
+    /** Environment variable the tool reads through state.env(). */
+    env: string;
+    scopes?: string[];
+    /** What the operator has to do to produce this credential. */
+    how: string;
+}
+export interface ConnectorManifest {
+    kind: 'mcp' | 'rest' | 'cli';
+    baseUrl?: string;
+    auth: 'oauth' | 'apikey' | 'none';
+    /** False means every tool in this app is read-only. */
+    writes: boolean;
+}
+export interface AppManifest {
+    /** URL-safe app slug. This is the registry key and the lookup handle. */
+    app: string;
+    title: string;
+    /** What people actually type: "snap", "insta", "gmail", "workspace mail". */
+    aliases: string[];
+    /** npm package name. */
+    package: string;
+    connector: ConnectorManifest;
+    credentials: CredentialRequirement[];
+    experts: ExpertManifest[];
+    /** Extra operator notes, e.g. platform review requirements. */
+    gate?: string;
+    /** Vendor terms that constrain what you may do with returned data. */
+    dataRetention?: string;
+}
+export interface Registry {
+    schema: 1;
+    generatedAt: string;
+    apps: AppManifest[];
+}
+/** True when `query` names this app by slug, title, or alias. */
+export declare function matchesApp(app: AppManifest, query: string): boolean;
+/** Every app whose slug, title, alias, or expert text contains the query. */
+export declare function searchApps(registry: Registry, query: string): AppManifest[];
+/** Resolve an app by exact handle (slug, title, or alias). */
+export declare function findApp(registry: Registry, query: string): AppManifest | undefined;
+/** Flatten an app's capabilities into `expert:action = level` lines. */
+export declare function describeCapabilities(app: AppManifest): string[];
+/**
+ * True when nothing the app *ships* can change state.
+ *
+ * Experts with status `gap` are declarations of intent, not code, so they are
+ * excluded — otherwise an unimplemented write path would make a read-only app
+ * report itself as write-capable.
+ */
+export declare function isReadOnly(app: AppManifest): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3D,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,YAAY,CAAC;IACrB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClC,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,WAAW,EAAE,qBAAqB,EAAE,CAAC;IACrC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,WAAW,EAAE,CAAC;CACrB;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAMnE;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAS3E;AAED,8DAA8D;AAC9D,wBAAgB,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAElF;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,EAAE,CAO/D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAMpD"}

package/dist/index.js

@@ -0,0 +1,56 @@
+/**
+ * Shared types for app-agents.
+ *
+ * One app manifest describes one app, the expert agents inside it, and
+ * exactly what those agents are allowed to do. The manifest is the source of
+ * truth for the registry, the CLI, and the "what can you promise a customer"
+ * answer.
+ */
+/** True when `query` names this app by slug, title, or alias. */
+export function matchesApp(app, query) {
+    const q = normalize(query);
+    if (!q)
+        return false;
+    if (normalize(app.app) === q)
+        return true;
+    if (normalize(app.title) === q)
+        return true;
+    return app.aliases.some((alias) => normalize(alias) === q);
+}
+/** Every app whose slug, title, alias, or expert text contains the query. */
+export function searchApps(registry, query) {
+    const q = normalize(query);
+    if (!q)
+        return registry.apps;
+    return registry.apps.filter((app) => {
+        const haystack = [app.app, app.title, ...app.aliases, ...app.experts.map((e) => `${e.id} ${e.title} ${e.job}`)]
+            .map(normalize)
+            .join(' ');
+        return haystack.includes(q);
+    });
+}
+/** Resolve an app by exact handle (slug, title, or alias). */
+export function findApp(registry, query) {
+    return registry.apps.find((app) => matchesApp(app, query));
+}
+/** Flatten an app's capabilities into `expert:action = level` lines. */
+export function describeCapabilities(app) {
+    return app.experts.flatMap((expert) => Object.entries(expert.capabilities).map(([action, level]) => `${expert.id}:${action} = ${level}${expert.status === 'gap' ? ' (planned)' : ''}`));
+}
+/**
+ * True when nothing the app *ships* can change state.
+ *
+ * Experts with status `gap` are declarations of intent, not code, so they are
+ * excluded — otherwise an unimplemented write path would make a read-only app
+ * report itself as write-capable.
+ */
+export function isReadOnly(app) {
+    const shipped = app.experts.filter((expert) => expert.status !== 'gap');
+    if (shipped.length === 0)
+        return true;
+    return shipped.every((expert) => Object.values(expert.capabilities).every((level) => level === 'read'));
+}
+function normalize(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@app-agents/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Shared manifest types and registry helpers for app agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/app-agents/agents.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/app-agents/agents#readme",
+  "bugs": {
+    "url": "https://github.com/app-agents/agents/issues"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.