@keystrokehq/skills 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @keystrokehq/skills
 
+## 0.0.8
+
+### Patch Changes
+
+- 2c08ba5: Fixing refresh and adding google lifecycle config
+
+## 0.0.7
+
+### Patch Changes
+
+- 7abf3aa: Add runtime script guidance and scaffold `@keystrokehq/runtime` into initialized projects.
+
 ## 0.0.6
 
 ### Patch Changes

package/README.md

@@ -16,6 +16,7 @@ The packaged skills are:
 - `keystroke-trigger-authoring`
 - `keystroke-task-authoring`
 - `keystroke-cli-workspace`
+- `keystroke-runtime-scripts`
 
 ## Editing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keystrokehq/skills",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "private": false,
   "type": "module",
   "publishConfig": {

package/src/_AGENTS.md

@@ -29,6 +29,8 @@ Keystroke also has one shared unit-of-work primitive: `Operation`.
 - Use the `Operation` name when describing shared infrastructure, integrations, or a reusable unit that can be used in both places.
 - The runtime behavior comes from context, not from which alias name was used in the constructor.
 
+For local TypeScript scripts, agents can import `@keystrokehq/runtime` to run `Operation` / `Step` / `Tool` instances with automatic credential loading from overrides, env vars, or saved Keystroke auth.
+
 Runtime boundary:
 
 - workflows and steps are authored as TypeScript control-flow and unit-of-work code

package/src/keystroke-runtime-scripts/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: keystroke-runtime-scripts
+description: Use @keystrokehq/runtime in local TypeScript scripts to run Keystroke Operation, Step, or Tool instances with credential loading and runtime context. Use when writing one-off scripts, local integration checks, or credential-backed operation runs outside Vitest.
+---
+
+# Keystroke Runtime Scripts
+
+Use this skill when an agent needs to run Keystroke operations from a local TypeScript or JavaScript script.
+
+Default split:
+- use `@keystrokehq/runtime` for local scripts and manual integration checks
+- use `@keystrokehq/testing` for Vitest tests, mocks, hooks, and deterministic assertions
+- use the CLI skill for workflow builds, deploys, credential upload, and deployed workflow runs
+
+## Quick start
+
+Install the runtime side effect once, then call `.run(...)` on an `Operation`, `Step`, or `Tool`.
+
+```ts
+import '@keystrokehq/runtime';
+
+import { listObjects } from '@keystrokehq/attio/objects';
+
+const objects = await listObjects.run({});
+console.info(JSON.stringify(objects, null, 2));
+```
+
+Or use the explicit helper:
+
+```ts
+import { run } from '@keystrokehq/runtime';
+import { listObjects } from '@keystrokehq/attio/objects';
+
+const objects = await run(listObjects, {});
+console.info(JSON.stringify(objects, null, 2));
+```
+
+## Configure runtime
+
+Use `configureRuntime(...)` for process-wide script settings:
+
+```ts
+import { configureRuntime } from '@keystrokehq/runtime';
+
+configureRuntime({
+  credentials: {
+    mode: 'auto',
+    overrides: {
+      attio: {
+        ACCESS_TOKEN: process.env.ATTIO_ACCESS_TOKEN,
+      },
+    },
+  },
+  workflowGlobals: {
+    tenantId: 'tenant_local',
+  },
+  stepContext: {
+    stepId: 'local-script',
+  },
+});
+```
+
+Credential modes:
+- `auto`: explicit overrides, env vars, then saved `keystroke auth` credentials
+- `env-only`: overrides and env vars only
+- `off`: no runtime credential resolver
+
+Use `withRuntime(options, callback)` when configuration must be scoped to one block. Use `createRuntime(options)` when you need an explicit handle and will call `runtime.dispose()`.
+
+## Rules
+
+- Keep scripts small and disposable.
+- Prefer operation `.run(input)` after the side-effect import for simple scripts.
+- Prefer `run(operation, input)` when the call site should make the runtime dependency obvious.
+- Put secret values in `credentials.overrides` or env vars named from the credential set, not in source.
+- Pass `workflowGlobals` when the operation expects typed workflow globals.
+- Pass `stepContext` only for local metadata such as `stepId`, attempts, tracing, or prefilled credentials.
+- Do not use runtime scripts as tests; use `@keystrokehq/testing` in `.test.ts` files.
+- Do not use `execution: 'cloud'`; local scripts currently use `execution: 'local'`.